项目定位与核心能力

Shumai 是一个面向创意协作的开源平台，用于集中管理媒体资产、协作反馈与 AI 增强的工作流。资料来源：README.md:1-30。

平台围绕以下几类核心能力构建：

• S3 兼容与本地存储：支持本地文件系统或任意 S3 兼容对象存储（AWS S3、Cloudflare R2、MinIO 等）保存图片与视频素材。
• 帧级注释与时间戳评论：在视频与图片上提供逐帧绘制工具与时间码评论，便于精确反馈。
• 安全分享与媒体集合：通过安全公开链接与策展集合对外协作。
• 细粒度访问控制：团队级与项目级两层 RBAC。
• 基于 Temporal 的分布式转码：将重负载的视频转码任务卸载至 Temporal worker 池。
• 自定义资产元数据：支持按管线定义动态字段。
• Shumai Agent：在工作空间内提供上下文感知的 AI 对话、可注册的脚本/工具、沙箱执行（基于 Anthropic 沙箱运行时）、Google Gemini 元数据自动填充以及基于向量嵌入的语义检索。

最新版本 v0.1.1 在 Docker 入口处增加了数据卷的权限降级（PR #151），强化容器化部署时持久化卷的主机侧安全边界。资料来源：v0.1.1 发布说明。

技术栈与运行时依赖

Shumai 基于 Bun 与 TypeScript 生态构建，由根 package.json 通过 workspaces: ["packages/*", "apps/*"] 将仓库组织为 Monorepo。Web 入口由 bun run --hot apps/web/src/index.ts 启动；后台 worker 由 worker:agent 与 worker:transcode 脚本启动；测试通过 Vitest 运行并依赖 @testcontainers/postgresql 拉起真实数据库实例。资料来源：package.json:1-50。

各子包的核心依赖反映了其职责：

• @shumai/api 使用 hono 框架、@hono/zod-validator 与 zod 做请求校验、pino 输出结构化日志、ulid 生成 ID。资料来源：packages/api/package.json:1-20。
• @shumai/core 聚合了鉴权（better-auth）、图像处理（sharp）、加密（tweetnacl）、压缩解压（adm-zip、extract-zip）、顺序索引（jittered-fractional-indexing）、时间处理（date-fns）以及 YAML 解析（yaml）。资料来源：packages/core/package.json:1-40。
• @shumai/agent 引入 @google/genai、@anthropic-ai/sandbox-runtime 与 @earendil-works/pi-agent-core/pi-ai，负责 AI 对话、工具注册与沙箱执行。资料来源：packages/agent/package.json:1-25。
• @shumai/transcode 与 @shumai/workflow-core 通过 @temporalio/{activity,workflow,worker,client} 进行后台任务编排。资料来源：packages/transcode/package.json:1-15、packages/workflow-core/package.json:1-15。
• @shumai/cli 复用 @shumai/api 与 @shumai/tableprinter，并以 hono 与 ulid 作为底层工具。资料来源：apps/cli/package.json:1-15。
• 数据层由 Prisma 管理，通过 db:migrate、db:deploy、db:generate 脚本运行迁移与客户端生成。资料来源：package.json:10-25。

Monorepo 工作区结构与运行时拓扑

各子包之间通过 workspace:* 协议相互引用。下图展示了主要的运行时进程与包依赖关系：

graph LR
  Web["apps/web<br/>@shumai/web-app"]
  CLI["apps/cli<br/>@shumai/cli"]
  AgentApp["apps/agent<br/>@shumai/agent-app"]
  TranscodeApp["apps/transcode<br/>@shumai/transcode-app"]

  subgraph Packages
    API["packages/api"]
    Core["packages/core"]
    DB["packages/db"]
    DTOs["packages/dtos"]
    WebUI["packages/webui"]
    Workflow["packages/workflow-core"]
    Agent["packages/agent"]
    Transcode["packages/transcode"]
    TP["packages/tableprinter"]
  end

  Web --> API
  Web --> WebUI
  Web --> Workflow
  Web --> Agent
  Web --> Transcode
  Web --> Core
  Web --> DB
  Web --> DTOs

  CLI --> API
  CLI --> Core
  CLI --> DTOs
  CLI --> TP

  AgentApp --> Agent
  AgentApp --> Core
  AgentApp --> Workflow

  TranscodeApp --> Transcode
  TranscodeApp --> Core
  TranscodeApp --> Workflow

  API --> Core
  API --> DB
  API --> DTOs
  Core --> DB
  Core --> DTOs
  Agent --> DB
  Agent --> DTOs
  Agent --> Core
  Transcode --> DB
  Transcode --> DTOs
  Transcode --> Core
  Workflow --> DB
  Workflow --> DTOs
  Workflow --> Core

从图中可以看出三类运行时进程：Web 服务面向浏览器与外部 API 调用方；后台 worker 由 Temporal 调度，可在容器中横向扩展；CLI 客户端通过 SHUMAI_API_SERVER 与 SHUMAI_API_KEY 与 API 通信。资料来源：apps/cli/README.md:1-30、apps/web/package.json:1-15、apps/agent/package.json:1-10、apps/transcode/package.json:1-10。

关键子系统设计

API 层

@shumai/api 基于 Hono 构建，路由文件中通过 authMiddleware 在请求上下文注入用户对象，并以此驱动后续的服务调用。资料来源：packages/api/src/project.test.ts:1-30。

权限模型由 authzService.hasPermission 配合 Permission 与 ResourceType 枚举实现，涵盖 Read、Edit、Admin 三档动作以及 Project、Asset 等资源类型。资料来源：packages/api/src/versionStack.test.ts:1-30。

@shumai/dtos 是 API、Worker、CLI 共享的 Zod schema 与类型定义，避免在多个进程间重复维护校验逻辑。资料来源：packages/dtos/package.json:1-10。

领域核心与基础设施

@shumai/core 是所有上层应用共用的业务服务层。它将鉴权、媒体处理、加密、压缩、顺序索引等横切能力封装为可复用的服务接口，避免在 API 与 Worker 中重复实现。资料来源：packages/core/package.json:15-40。

CLI 入口位于 apps/cli/src/index.ts，负责解析 project ls、ls、mkdir、upload、create-version 等子命令，其中后四项必须通过 -p/--parent 指定父目录或资产 ID。命令输出经过 @shumai/tableprinter 渲染为表格，提升终端可读性。资料来源：apps/cli/src/index.ts:1-50、packages/tableprinter/package.json:1-10。

工作流与后台任务

转码与 Agent 任务均通过 Temporal 编排。@shumai/workflow-core 提供共享的 Temporal 客户端与 worker 装配逻辑，使业务包（@shumai/transcode 与 @shumai/agent）只需专注于 activity 实现。apps/agent/src/index.ts 与 apps/transcode/src/index.ts 是两个独立的可执行入口，对应根 package.json 中的 worker:agent 与 worker:transcode 脚本。资料来源：packages/workflow-core/package.json:1-15、packages/transcode/package.json:1-15、packages/agent/package.json:15-25。

部署、运维与故障排查

• 开发与构建：根 package.json 提供 dev、typecheck、lint、test、format、build 等脚本，覆盖类型检查、Lint、Vitest 单元测试、Prettier 格式化与产物构建。
• 数据库：db:migrate、db:deploy、db:generate 三条脚本分别对应开发迁移、生产部署与 Prisma Client 生成。资料来源：package.json:10-25。
• 容器安全：v0.1.1 在 Docker 入口脚本中加入了 root 权限降级逻辑，确保写入持久化数据卷时使用非特权用户。资料来源：PR #151。
• 常见失败模式：若未先部署 Temporal 服务就启动 worker:transcode 或 worker:agent，后台任务将无法被调度；CLI 报错时需先确认 SHUMAI_API_SERVER 与 SHUMAI_API_KEY 已正确导出。资料来源：apps/cli/README.md:10-25。

See Also

• 内部 API 路由实现：packages/api/src/
• 工作流与 worker 实现：packages/workflow-core/、apps/transcode/、apps/agent/
• CLI 使用方式与命令列表：apps/cli/README.md、apps/cli/src/index.ts
• 版本发布记录：GitHub Releases

一、平台整体架构

Shumai 是一个面向创意协作场景的开源平台，提供资产存储、标注评论、安全共享、权限管理、分布式转码以及 AI Agent 等能力 README.md:1-40。代码以 monorepo 形式组织，使用 Bun 作为运行时与构建工具，并在根目录中通过 workspaces 字段统一管理 packages/* 与 apps/* package.json:8-10。仓库中定义了多个顶层脚本，例如 dev、build、db:migrate、worker:agent 与 worker:transcode，分别覆盖本地开发、生产构建、数据库迁移以及后台 Worker 启动等场景 package.json:12-30。

平台在逻辑上可以划分为三个层次：

• 数据与领域层：packages/db（Prisma 持久化）、packages/dtos（Zod 校验的领域模型）。
• 核心服务层：packages/core（资产、S3、鉴权等核心服务）以及基于 Hono 的 packages/api。
• 应用与 Worker 层：apps/web（Web 入口）、apps/cli（命令行工具）、apps/transcode（转码 Worker）以及 apps/agent（Agent Worker）。

各包之间通过 workspace:* 协议互相依赖，例如 packages/api 依赖 @shumai/core、@shumai/db、@shumai/dtos packages/api/package.json:10-15；apps/transcode 则依赖 @shumai/transcode、@shumai/core 和 @shumai/workflow-core apps/transcode/package.json:9-14。@shumai/core 内部集成了 better-auth、sharp、adm-zip、hono、tweetnacl 等库，承担权限、图片处理、压缩、HTTP 服务等横切职责 packages/core/package.json:9-25。

二、数据模型与 DTO 设计

@shumai/dtos 是整个平台共享契约的中心：所有 API 请求、响应与持久化对象都通过 Zod Schema 描述，并在前后端、CLI、Worker 之间复用 packages/dtos/src/index.ts:1-20。该包统一导出了 agent、ai、asset、auth、collection、folder、invite、metadata、notification、pagination、project、provider、s3、search、share、skill、team、upload、user-metadata、versionStack 等模块，每个模块对应一个核心领域实体 packages/dtos/src/index.ts:1-20。

以团队（Team）模型为例，teamInfoSchema 描述了 id、name、rootFolder、updatedAt 等字段，并通过 Zod 的 infer 直接生成 TS 类型，便于在 API 和数据库层共享同一个契约 packages/dtos/src/team.ts:7-15。getMeResponseSchema 明确把用户角色枚举约束在 owner、editor、reviewer、bot、unknown 五种取值之内 packages/dtos/src/team.ts:34-43。paginationParamsSchema 与 paginationPageInfoSchema 则提供统一的分页协议，被 getUserTeamsRequestSchema、getUserTeamsResponseSchema 复用，避免每个接口重复定义分页结构 packages/dtos/src/team.ts:1-30。

模型提供方（Provider）部分，DTO 抽象出可序列化的 providerModelConfigSchema，包含推理开关、输入模态、上下文窗口、最大 Token 以及按输入/输出/缓存读写细分的费用结构 packages/dtos/src/provider.ts:11-25。KNOWN_APIS 枚举目前覆盖 openai-completions、anthropic-messages、google-generative-ai、bedrock-converse-stream 等主流大模型接入协议，平台可在不改动上层业务的前提下替换底层模型 packages/dtos/src/provider.ts:3-13。providerConfigSchema 使用 z.string().url() 校验 baseUrl，确保外部服务地址合法 packages/dtos/src/provider.ts:27-40。

三、API 层与权限控制

@shumai/api 基于 Hono 框架构建，通过 @hono/zod-validator 把 DTO Schema 翻译为运行时校验，配合 pino 输出结构化日志 packages/api/package.json:12-19。从测试代码可见，API 在路由层统一挂载了 authMiddleware 把 user 写入 Hono 的 Variables 上下文，再由 authzService 执行 hasPermission 鉴权，随后委托给领域服务完成业务 packages/api/src/project.test.ts:1-40。

以 metadataRoute 为例，调用方传入团队 ID 后，路由先读取当前用户，再调用 authzService.hasPermission 判断是否具备 ResourceType 上对应权限，最后委托给 metadataService 返回 fields、readOnly、aiAutofill 等结构 packages/api/src/metadata.test.ts:1-30。agentRoute 测试中展示了创建与更新 Agent 的典型模式：POST /teams/:teamId/agents 校验 name、type、providerId、modelId、thinkingLevel、systemPrompt、soul、skills 字段，缺一即返回 400 packages/api/src/agent.test.ts:1-30。

CLI 工具 apps/cli 直接复用 packages/api 的路由与 DTO，通过环境变量 SHUMAI_API_SERVER 与 SHUMAI_API_KEY 与服务端通信，命令包括 project ls、folder ls、upload 等 apps/cli/README.md:1-60。

四、后台 Worker 与执行流

除同步 API 外，平台通过 Temporal 调度两类长时间任务：转码与 Agent 推理。packages/transcode 与 apps/transcode 共同封装 @temporalio/worker、@temporalio/workflow、@temporalio/activity，把视频转码从 API 路径剥离到后台 packages/transcode/package.json:9-17。

Agent Worker 端，核心执行流由 executeAgentPrompt 协调：当用户发起聊天或元数据自动填充请求时，Worker 先通过 initializeAgentSessionActivity 确保 Agent 用户在 Prisma 中存在并以 type='agent' 标识，再调用大模型并把工具调用结果回写数据库 packages/agent/src/activities/agent.ts:1-60。自动填充（autofill_metadata）任务会把抽取结果以 JSON 形式回传到 Temporal 活动，由持久化层继续写入 MetadataField 表 packages/agent/src/activities/agent.ts:1-40。

flowchart LR
    Client[Web / CLI] --> API[Hono API]
    API --> Core[core services]
    Core --> DB[(Prisma DB)]
    API --> Temporal[Temporal]
    Temporal --> Agent[Agent Worker]
    Temporal --> Transcode[Transcode Worker]
    Agent --> Provider[LLM Provider]
    Transcode --> S3[(S3 / 本地存储)]
    Core --> S3

五、近期变更

最新版本 v0.1.1 中，社区合入了 #151 提交：为 Docker 镜像增加了根用户入口脚本并在挂载数据卷时完成权限降级，从而避免容器内进程以 root 身份直接读写宿主目录 README.md:1-40。这一改动对所有使用 Docker Compose 部署的用户都会产生影响，建议在升级后重新确认数据卷挂载点的属主与权限。

See Also

• 资产与 S3 存储
• AI Agent 与工作流
• 权限与团队管理

概述与设计目标

Shumai 是一个面向创意协作的开源平台，其 AI Agent 子系统旨在为项目工作区提供上下文感知的对话助手，并支持 AI 自动元数据填充、向量检索与脚本沙箱执行。Agent 的核心入口在 packages/agent/src/index.ts 中导出，通过 createAgentSession 创建可被 Temporal 工作流调用的会话实例，并依赖 @earendil-works/pi-agent-core 与 SandboxManager 协同完成模型调用、工具调度与安全隔离。资料来源：packages/agent/src/index.ts:1-30。

整个 Agent 体系的设计目标在 README.md 中被概括为四项：协作式 AI 对话、可扩展的自定义技能与工具、隔离的沙箱执行环境，以及基于 Google Gemini 的 AI 元数据自动填充与语义检索。资料来源：README.md:30-44。

核心架构

Agent 子系统采用「Temporal 工作流 + 活动函数 + 工具库」三层结构。Temporal 工作流负责编排长时任务与重试策略，活动函数承载具体的副作用调用（如会话初始化、评论创建、嵌入生成），工具库则通过 AgentTool 抽象暴露给模型调用。

flowchart LR
  User[用户评论/聊天] --> WF[agent-chat / agent-autofill 工作流]
  WF --> ACT[Activities: agent / ai]
  ACT --> Session[createAgentSession]
  Session --> Harness[AgentHarness + Model]
  Harness --> Tools[AgentTool 工具集]
  Tools -->|create_file| FS[云端文件系统]
  Tools -->|screenshot| SC[截图服务]
  Tools -->|sandboxed_bash| SB[SandboxManager]
  ACT --> Embed[generateEmbedding]
  WF --> Result[评论/元数据/嵌入结果]

工作流与活动均通过 executeActivity 与 getActivities 注入到测试环境，这一模式在 packages/agent/src/workflows/agent-chat.test.ts 中通过 vi.mock('@shumai/workflow-core') 显式验证。资料来源：packages/agent/src/workflows/agent-chat.test.ts:1-30。

Agent 会话与提示词构建

createAgentSession 在 packages/agent/src/index.ts 中接收 teamId、agentId、providerName、modelId 等参数，并使用 DatabaseSessionStorage 将对话历史持久化到 Prisma 数据库。系统提示词在 packages/agent/src/activities/agent.ts 中拼接：基础说明 + 平台行为规范 + agent.soul 人格定义 + 上下文指令。资料来源：packages/agent/src/activities/agent.ts:30-100。

AgentChatPromptBuilder 是会话提示词的可组合构建器，支持 withExplicitMention、withPathContext、withAssetDetails 等链式调用，按资产类型（图片或视频）动态注入工具建议（例如图片资产触发 analyze_image，视频资产触发 screenshot）。该行为在 packages/agent/src/workflows/agent-chat-prompt-builder.test.ts 中通过单测明确锁定。资料来源：packages/agent/src/workflows/agent-chat-prompt-builder.test.ts:1-30。

initializeAgentSessionActivity 会在数据库中补齐 agent 类型用户与 Agent 记录，确保 AI 在评论流中以独立身份出现。资料来源：packages/agent/src/activities/agent.ts:130-180。

Agent 工具系统

工具以 AgentTool 类型实现，统一通过 Type.Object 定义输入 schema。packages/agent/src/index.ts 中可见的工具包括：analyze-image、screenshot、create-file、create-folder、create-version、list-assets、read-skill 与 sandboxed-bash，全部通过 executeAgentToolWorkflow 桥接到 Temporal 工作流。资料来源：packages/agent/src/index.ts:60-120。

create-file 与 create-version 共享相同的 MIME 探测与回退表（.png、image/png、.mov、video/quicktime 等），表明二者源自同一上传管道但落地语义不同。资料来源：packages/agent/src/tools/create-file.ts:1-50、资料来源：packages/agent/src/tools/create-version.ts:1-50。沙箱安全模型在 packages/agent/src/index.test.ts 中通过 SandboxAskCallback 模拟验证。资料来源：packages/agent/src/index.test.ts:1-40。

模型与供应商配置通过 Zod schema 序列化在 packages/dtos/src/provider.ts 中定义，支持 OpenAI、Anthropic、Google、Bedrock 等多种 API 形态，并通过 providerModelConfigSchema 描述 contextWindow、maxTokens 与成本字段。资料来源：packages/dtos/src/provider.ts:1-40。

Temporal 工作流编排

根 package.json 暴露两条 worker 启动脚本：worker:agent 与 worker:transcode，分别对应 apps/agent/src/index.ts 与 apps/transcode/src/index.ts，表明 Agent 与转码均为独立的 Temporal worker 进程。资料来源：package.json:30-50。apps/agent/package.json 通过 bin.shumai-agent 暴露可执行入口，便于在容器中以最小权限启动。资料来源：apps/agent/package.json:1-12。

工作流核心文件导出列表（agent-autofill、agent-chat、agent-embedding、agent-tool-call、query-embedding-for-search）显示 Agent 子系统同时承担对话、自动填充、嵌入生成、工具调用与语义检索五类长时任务。资料来源：packages/agent/src/index.ts:1-30。agentChatActivity 与 autofillAiActivity 在 packages/agent/src/activities/agent.test.ts 中通过 mock AgentHarness.prompt 验证提示注入路径。资料来源：packages/agent/src/activities/agent.test.ts:1-40。

需要注意的是，agent.provider 或 agent.modelRef 缺失时会以 nonRetryable: true 抛出 ApplicationFailure，避免 Temporal 对配置错误进行无限重试。资料来源：packages/agent/src/activities/agent.ts:50-90。

See Also

• 项目首页与功能总览：README.md
• DTO 与模型配置：packages/dtos/src/index.ts
• 工作流测试基线：packages/agent/src/workflows/agent-chat.test.ts
• Agent Worker 启动入口：apps/agent/package.json
• 最新发布说明（v0.1.1，Docker 入口权限收敛）：GitHub Releases

1. 仓库结构与工作区

Shumai 是一个使用 Bun 工作区（Bun workspaces）组织的 monorepo 项目。从根目录 package.json 可知，工作区声明覆盖了 packages/* 与 apps/* 两个目录，整个仓库统一启用 ESM（"type": "module"），便于跨包直接 import TypeScript 源码。 资料来源：package.json:1-19

在 packages/ 目录下集中放置可复用业务包：

• @shumai/core：核心业务能力、权限、存储与图像处理；依赖 better-auth、sharp、adm-zip、hono 等关键库。 资料来源：packages/core/package.json:1-32
• @shumai/api：基于 Hono 的 HTTP API 路由层。 资料来源：packages/api/package.json:1-19
• @shumai/dtos：使用 Zod 定义的统一 DTO，涵盖 agent、asset、auth、collection、folder、metadata、project、share、skill、team 等模块。 资料来源：packages/dtos/src/index.ts:1-19

apps/ 下则是可独立运行的入口应用：web、cli、transcode 等。

2. Web UI 应用

apps/web 是面向最终用户的前端入口应用，它自身只承担 HTTP 服务端引导与请求转发，业务逻辑由工作区包提供。其依赖列表显式声明了 @shumai/api、@shumai/core、@shumai/db、@shumai/dtos、@shumai/workflow-core、@shumai/agent、@shumai/transcode、@shumai/webui 等内部包。 资料来源：apps/web/package.json:1-15

开发模式下，根脚本使用 Bun 的 --hot 热重载能力启动 Web 服务：

bun run dev   # 等价于 bun run --hot apps/web/src/index.ts

数据库相关脚本同样在根 package.json 中集中管理：db:migrate（开发态）、db:deploy（生产态）、db:generate（生成 Prisma Client）。 资料来源：package.json:7-15

3. CLI 工具

apps/cli 是一个独立命令行工具，bin 字段声明入口名为 shumai-cli，通过内部 @shumai/api、@shumai/core、@shumai/dtos 与 @shumai/tableprinter 等工作区包与 Hono 客户端访问 API。 资料来源：apps/cli/package.json:1-14

使用前必须设置两个环境变量完成认证： 资料来源：apps/cli/README.md:13-21

• SHUMAI_API_SERVER：Shumai API 服务地址，例如 http://localhost:3000。
• SHUMAI_API_KEY：在 WebUI「Settings → Developer」选项卡下生成的开发者 Token。

CLI 支持的项目括：列出项目（project ls）、列出目录内容、创建文件夹、上传文件或目录、以及为既有文件创建新版本。需要特别注意的是，因为 CLI 入口文件使用 #!/usr/bin/env node shebang，Bun 用户需要在命令前加 bun run --bun 前缀，否则会落到 Node.js 运行时。 资料来源：apps/cli/README.md:26-30

4. 部署与运维

4.1 Docker Compose 快速部署

官方推荐使用 Docker Compose 作为最快上手方式：新建一个目录，下载 docker-compose.yaml，然后执行 docker compose up -d 即可。 资料来源：README.md:42-49 该方式默认使用本地文件系统作为存储后端，避免了 S3 等外部依赖。

4.2 后台 Worker 进程

根 package.json 暴露了若干 Worker 启动脚本，按职责分离后台任务： 资料来源：package.json:18-19

apps/transcode 作为独立可执行入口，依赖 @shumai/transcode、@shumai/core、@shumai/workflow-core，由此可推断转码任务由 Temporal 工作流驱动，并交由专门的 worker 进程消费。 资料来源：apps/transcode/package.json:1-12

4.3 v0.1.1 关键运维变更（PR #151）

最新发布 v0.1.1 引入了一个与部署直接相关的改进：feat(docker): add root entrypoint with privilege dropping for data volumes（#151）。该 PR 在 Docker 入口脚本中以 root 身份完成数据卷挂载目录的初始化，再降权到非特权用户运行主进程，从而在保留容器启动便利性的同时提升了数据卷场景下的安全性。 资料来源：README.md

4.4 构建与发布

仓库根脚本还提供了完整的发布链路：build、build-npm、publish、release:patch|minor|major 等。其中 prepublishOnly 会在发布前依次执行 build-npm、lint、typecheck，作为发布前的质量门禁。 资料来源：package.json:22-34

5. 小结

• Web UI：由 apps/web 启动，业务能力来自 @shumai/webui、@shumai/api 等工作区包；通过 bun run dev 进入开发模式。
• CLI：apps/cli 通过 Hono 客户端调用 REST API，需配置 SHUMAI_API_SERVER 与 SHUMAI_API_KEY；Bun 用户须使用 bun run --bun 前缀。
• 部署：推荐 Docker Compose 一键拉起；后台按需启动 worker:agent 与 worker:transcode。
• v0.1.1：Docker 入口脚本增加了 root 初始化后降权的能力，强化了数据卷场景下的安全模型。

Pitfall Log / 踩坑日志

项目：shumaione/shumai

摘要：发现 6 个潜在踩坑项，其中 0 个为 high/blocking；最高优先级：能力坑 - 能力判断依赖假设。

1. 能力坑 · 能力判断依赖假设

• 严重度：medium
• 证据强度：source_linked
• 发现：README/documentation is current enough for a first validation pass.
• 对用户的影响：假设不成立时，用户拿不到承诺的能力。
• 证据：capability.assumptions | https://news.ycombinator.com/item?id=48642686 | README/documentation is current enough for a first validation pass.

2. 维护坑 · 维护活跃度未知

• 严重度：medium
• 证据强度：source_linked
• 发现：未记录 last_activity_observed。
• 对用户的影响：新项目、停更项目和活跃项目会被混在一起，推荐信任度下降。
• 证据：evidence.maintainer_signals | https://news.ycombinator.com/item?id=48642686 | last_activity_observed missing

• 严重度：medium
• 证据强度：source_linked
• 发现：no_demo
• 证据：downstream_validation.risk_items | https://news.ycombinator.com/item?id=48642686 | no_demo; severity=medium

4. 安全/权限坑 · 存在评分风险

• 严重度：medium
• 证据强度：source_linked
• 发现：no_demo
• 对用户的影响：风险会影响是否适合普通用户安装。
• 证据：risks.scoring_risks | https://news.ycombinator.com/item?id=48642686 | no_demo; severity=medium

5. 维护坑 · issue/PR 响应质量未知

• 严重度：low
• 证据强度：source_linked
• 发现：issue_or_pr_quality=unknown。
• 对用户的影响：用户无法判断遇到问题后是否有人维护。
• 证据：evidence.maintainer_signals | https://news.ycombinator.com/item?id=48642686 | issue_or_pr_quality=unknown

6. 维护坑 · 发布节奏不明确

• 严重度：low
• 证据强度：source_linked
• 发现：release_recency=unknown。
• 对用户的影响：安装命令和文档可能落后于代码，用户踩坑概率升高。
• 证据：evidence.maintainer_signals | https://news.ycombinator.com/item?id=48642686 | release_recency=unknown