Agent Check-in 用：「改什么 → 去哪个文件」。
完整架构设计、数据流与 ADR 叙事见docs/ARCHITECTURE.md。
开发任务见specs/core/tasks.md。
| 层 | 目录 | 职责 |
|---|---|---|
| Layer 1 Governance | CLAUDE.md、.cursor/rules/、.github/copilot-instructions.md |
铁律、命令、Check-in — Agent 入口路由 |
| Layer 2 Product Truth | specs/ |
proposal、design、tasks — 产品需求快照（历史） |
| Layer 3 Runtime State | memory/ |
进度、踩坑、决策 — 跨会话运行态 |
| Layer 4 Execution | .claude/workflows/、.cursor/ |
操作剧本（须符合 CLAUDE.md §Layer 4 约束） |
| Layer 5 Evidence | runs/ |
runs/<run_id>/ 工作流证据；runs/verification/ 测试/覆盖率报告归档 |
CLAUDE.md（治理规则） > memory/DECISIONS.md（最新决策） > specs/（历史快照） > runs/（执行记录）
specs/core/proposal.md一旦与其他文档冲突，永远不是权威来源，只用于查证「最初的想法是什么」。
所有自定义日志/事件输出遵循 CLAUDE.md §日志与事件字段规范（run_id、node_id、source、level、message、timestamp）。
| 想改什么 | 去哪里 |
|---|---|
| 铁律、命令、Check-in | CLAUDE.md |
| 想增强 Chat 自研 Clutch Agent（手脚/Plan/MCP/对话 UX/分层 prompt） | specs/core/clutch-agent-capability-plan.md · D44 · D53 |
| 产品介绍文档 | docs/PRODUCT_INTRO.md |
| Design 模式产品介绍（WHAT/WHY） | docs/DESIGN_PRODUCT_INTRO.md |
| Design 模式业务逻辑指南 | docs/DESIGN_WORKSPACE_GUIDE.md |
| 战略设计寄存器（impeccable） | 根目录 PRODUCT.md |
| Reasonix 本地权限（数据目录已 gitignore） | 根目录 reasonix.toml · .reasonix/ |
| 新手入门（中英） | docs/GETTING_STARTED.md · 仓库 README.md / README.zh-CN.md |
| 文档总索引 | docs/README.md |
| 系统架构图 | 叙事 docs/ARCHITECTURE.md（本地 HTML 预览不入库） |
| 开源 / DMG 分发排期（OSR-xx） | docs/OPEN_SOURCE_RELEASE.md |
| 应用内更新（Prep / Go-live） | docs/UPDATES.md · .github/workflows/release-updater.yml |
| Sidecar 热更（D37） | apps/desktop/src-tauri/src/sidecar_patch.rs · apps/desktop/src/services/sidecarPatch.ts · SidecarPatchReady.tsx · scripts/write-sidecar-patch-manifest.sh |
| 开源协议 | LICENSE |
| 漏洞报告 | SECURITY.md |
| 外部审计委托 / 报告入口 | docs/EXTERNAL_AUDIT.md · docs/security-audit/ |
| 社区行为准则 | CODE_OF_CONDUCT.md |
| 版本变更 | CHANGELOG.md（已发 v1.4.0；开发中 ## [1.4.1] - Unreleased） · 快照 docs/releases/ |
| Goals / Non-Goals | docs/PROJECT_SCOPE.md |
| API / Schema 稳定性 | docs/STABILITY.md |
| 扩展点边界 | docs/EXTENSIBILITY.md |
| 维护者治理 | docs/GOVERNANCE.md |
| 贡献指南（Phase 1 政策） | CONTRIBUTING.md |
| 性能基线（含本机实测 §1.1） | docs/PERFORMANCE.md |
| Apple 签名 / 公证（阻塞说明） | docs/APPLE_NOTARIZATION.md |
| 源码构建 | docs/BUILD_FROM_SOURCE.md |
| 环境自检 | scripts/doctor.sh |
| 终端用户安装（DMG/NSIS） | scripts/install.sh · scripts/install.ps1 |
| Homebrew tap | fancy1108/homebrew-clutch · scripts/sync-homebrew-tap.sh · docs/PACKAGE_MANAGERS.md |
| 维护者发版 / tap 同步 | docs/RELEASE_MAINTAINER.md |
| Tauri 桌面开发（Hybrid） | scripts/tauri-dev.sh · 根目录 pnpm tauri:dev |
| 产品需求历史 | specs/core/proposal.md（指针）· specs/archive/proposal-v0.1.md |
| 历史叙事归档 | docs/archive/ · specs/archive/ |
| 视觉设计快照 | specs/core/design.md → docs/UI_UX_GUIDELINES.md |
| 一键原型与交互契约规范 (PRD) | specs/core/prd-one-click-interactive-prototype.md |
| D34 Terminal Orchestra 执行计划 | specs/core/d34-terminal-orchestra-plan.md · UI 参考 experiments/d34_terminal_orchestra_ui/ |
| Design 出码质量改进计划（历史） | specs/core/design-quality-improvement-plan.md |
| 交互理解引擎 (IUE) — 6 阶段管道 | services/orchestrator/src/iue/ (models.py, engine.py, __init__.py) |
| 原型预览 API（接入 IUE） | services/orchestrator/src/routes/preview.py |
| React 代码生成器 | services/orchestrator/src/codegen/ (react_generator.py, __init__.py) |
| 交互契约持久化 | services/orchestrator/src/design/router.py (/contract 端点) |
| 前端 UI 规范（权威） | docs/UI_UX_GUIDELINES.md |
| macOS / Windows 平台 UI 边界 | docs/PLATFORM_MAINTENANCE.md · apps/desktop/src/platform/chrome/ |
| 开发任务清单（含 Verification） | specs/core/tasks.md |
| Chat Clutch Agent 能力表（D44） | specs/core/clutch-agent-capability-plan.md · 决策 memory/DECISIONS.md D44 · ROADMAP §Chat Clutch Agent |
| D25 Hybrid Runtime Task（HRT） | specs/core/hybrid-runtime-plan.md |
| 前端可点验模块（FM-xx · D56） | specs/core/frontend-modules-plan.md · ROADMAP §Frontend modules · 点验剧本 docs/FRONTEND_MODULES_ACCEPTANCE.md |
| Flow 多 Agent 接力 Task（D23） | specs/core/tasks.md §M3-F · Flow 多 Agent 接力 |
| Prototype → Task 全量映射 | specs/core/tasks.md §Prototype → Task 映射 |
| 待建 pytest 与 task 映射 | specs/core/tasks.md §待建 pytest 文件 |
| 里程碑级验收 T-01~04 | specs/core/tasks.md §测试与验收 |
| 进度 / 待办 | memory/PROGRESS.md（近期）· 归档 memory/archive/PROGRESS-2026-Q2.md · PROGRESS-2026-Q3.md · PROGRESS-2026-Q3-late.md |
| 发版产品快照 | 当前 v1.4.0 · docs/releases/ · docs/releases/v1.4.0.md |
| 候选优化需求池（未立项） | memory/BACKLOG.md · Active；B-01/04/05/06/08/10/18–22/42/43/46/47/49 已升格 FM-xx（D56） |
| GitHub Issue 待修复 Bug | memory/BACKLOG.md §GitHub Issues · 待修复 Bug |
| 开源排期 OSR-xx 验收状态 | memory/ROADMAP.md §开源分发 · Task 定义 docs/OPEN_SOURCE_RELEASE.md §7.2 |
| 文档生命周期 / 权威真相 | docs/document-governance.md |
| Orchestrator 主控能力调研（参考） | docs/research/orchestrator-optimization-pool.md |
| Clutch Agent ↔《深入理解 AI Agent》01–10 缺口（参考） | docs/research/clutch-agent-book-gap.md · 候选 B-42–B-43、B-46–B-47、B-49–B-50 · B-34–B-41、B-44、B-45、B-48 已升格 · Q-AGENT-1–4 |
| CLI PTY Session 改造方案（参考） | docs/research/pty-session.md |
| D25 Hybrid 执行状态（权威） | specs/core/hybrid-runtime-plan.md · D27 命名对齐 |
| PTY Session Step 0 实验 | experiments/pty_poc/ |
| TUI 嵌入 Phase 0 实验 | experiments/tui_embed_poc/ |
| 交互 PTY Runtime（终端模式） | services/orchestrator/src/interactive_pty_runtime.py |
| Task 交付索引（Commit / 证据） | memory/DELIVERABLES.md · 归档 memory/archive/DELIVERABLES-*.md |
| 决策与开放问题 | memory/DECISIONS.md |
| 功能验收状态 | memory/ROADMAP.md |
| 测试门禁状态 | memory/TESTS.md |
| Layer 4 边界与剧本约束 | CLAUDE.md §Layer 4 操作剧本 |
| 验收偏差 / 实现漂移物理诊断 | .claude/workflows/truth-alignment.md |
| 想改什么 | 去哪里 |
|---|---|
| 测试策略与 E2E 范围 | memory/DECISIONS.md（D1） |
| E2E 落地前提勾选 | memory/ROADMAP.md §E2E 落地前提 |
| 后端单元测试（现有 + 随 task 新建） | services/orchestrator/tests/；清单见 tasks.md §待建 pytest |
| Video Core 测试 | services/orchestrator/tests/test_video_core/ |
| CI 工作流 | .github/workflows/ci.yml |
| Secret scanning（gitleaks） | .github/workflows/secret-scan.yml |
| 本地一键校验 | scripts/verify.sh |
| Hybrid run 诊断导出（HRT-07） | scripts/export-run-debug.sh → GET /api/runs/{id}/debug |
| POC #6/#10 自动化验收（HRT-10） | scripts/verify-hybrid-poc-06-10.sh · services/orchestrator/tests/test_hybrid_poc_acceptance.py |
| D29 audit 回归（并发 rejection） | services/orchestrator/tests/test_hybrid_audit_d29_regression.py |
| 文档↔代码漂移机检 | scripts/check-doc-drift.sh |
| Git pre-commit（条件触发） | .husky/pre-commit |
| Git prepare-commit-msg（去掉 Cursor trailer） | .husky/prepare-commit-msg |
| 验证报告归档 | runs/verification/（gitignore） |
| E2E 包（M2-10，D1 可执行后） | e2e/；见下表 |
| E2E 沙箱与门禁 | scripts/e2e-sandbox-setup.sh；scripts/run-e2e.sh；runs/verification/.e2e-env |
| E2E Node WS 助手 | e2e/helpers/ws.ts |
| E2E Sidecar HTTP 助手 | e2e/helpers/sidecar.ts（waitForRunUsage） |
| E2E 桌面 Tauri 助手 | e2e/helpers/tauri.ts（authorizeSandboxWorkspace） |
| E2E 会话预置（Node） | e2e/helpers/seed.ts |
E2E API：session-history |
e2e/tests/session-history.spec.ts |
| E2E API：Overview 用量 | e2e/tests/session-usage.spec.ts |
| E2E API：i18n 偏好 | e2e/tests/i18n.spec.ts |
| E2E API：workspace git | e2e/tests/workspace-git.spec.ts |
| E2E Desktop fixture | e2e/fixtures/desktop.ts（@srsholmes/tauri-playwright） |
| E2E Desktop 全 UI | e2e/tests/desktop/all-ui.spec.ts |
| E2E Desktop 历史续聊 | e2e/tests/desktop/session-history.spec.ts |
| E2E Desktop Overview 用量 | e2e/tests/desktop/session-usage.spec.ts |
| E2E Tauri 沙箱 command | apps/desktop/src-tauri/src/lib.rs → clutch_e2e_sandbox |
| E2E 工作区注入（前端） | apps/desktop/src/services/pickWorkspaceFolder.ts |
| 想改什么 | 去哪里 |
|---|---|
| 应用根布局、ClutchState 投影 | App.tsx |
WebSocket store、useClutchState |
services/clutchState.ts · 纯辅助函数见 services/clutchStateUtils.ts |
| 会话 / 运行 API | services/runApi.ts |
| Skills Registry API（P2-01） | services/skillsApi.ts |
| Theme 偏好 API（P2-03） | services/themeApi.ts（含 language） |
| General 默认工作区 / 停止确认（FM-01） | services/permissionApi.ts · /api/preferences/default-workspace · high-risk-confirm |
| 本机信任 MCP（FM-02） | permissionApi.ts local-trust · General untrusted-confirm-toggle · Hub Enable；自建 SOP 不确认（D58） |
| Exec policy UI（FM-03） | ExecPolicyPanel.tsx · Settings Tools · /api/preferences/permission-rules |
| Codex 只读扫描（FM-04） | MoreAgentsComingSoon.tsx · cli_agent_config.py · More → Codex |
| Orchestra 发送即派发（D66/D67） | OrchestratorBar.tsx · terminal_orchestra.py；无确认卡/排队条/Complete 草稿 |
| 派发保存为工作流（FM-07） | OverviewDispatchLog.tsx save-dispatch-as-workflow |
| 对话模式 handoff（FM-08） | ChatInputBar.tsx drafts · orchestrator-fill-bar · 切 Terminal 预填近期对话 |
| 主控分派横幅（FM-09） | ChatFeed.tsx dispatch-banner |
| 画布节点引擎（FM-10 / D65） | WorkflowOrchestration.tsx Assigned Agent node-agent-select · Overview step-engine-*（跟 Agent 类型，无 Node engine 下拉） |
| 并行 worktree（FM-11） | WorktreeIsolationBar.tsx FooterWorktreeMenu · footer-worktree-trigger · GET/POST /api/worktree |
| Chat WS re-export | services/api.ts（re-export clutchState；M2 已去 mock） |
| 侧栏（工作区 / 历史，M2-07/09） | sidebar.tsx |
| 底部状态栏（Branch / Model / Agent · 容器宽度自适应） | App.tsx footer · FooterMenu.tsx FooterField* |
| 工作区 Git 分支 API | services/workspaceApi.ts → GET /api/workspace/git |
| Chat 流与人工干预 UI | components/ChatFeed.tsx |
| Chat 工具步骤条解析（D46） | services/agentActivitySteps.ts |
| 用系统浏览器打开本地 HTML | services/openInSystem.ts · Tauri clutch_open_path（src-tauri/src/lib.rs） |
| Chat 工具轨迹 UI（D46 verb_group） | components/AgentLiveActivity.tsx |
| Chat ↔ Terminal 同步（D51） | services/chatTerminalSync.ts · AgentLiveActivity / SubtaskCardView 「在 Terminal 查看」 |
| Chat 斜杠命令（D18） | services/slashCommands.ts · ChatInputBar / 面板 · POST /api/runs/{id}/compact |
| Goal 跟踪（D29） | builtin goal_write · GoalBarView.tsx · ClutchState.goal |
| 会话看板（D30） | SessionOverviewBoard.tsx · ChatInputBar 底栏 Sessions 入口 |
| Chat Composer（极简 + 菜单） | ChatInputBar.tsx 仅 +/模式/发送 · 次要能力进 + 菜单 · Worktree 在 App footer · ScheduledTasksBar 受控面板 · PRODUCT.md / docs/UI_UX_GUIDELINES.md §4.3 |
| Agent 忙时排队（D20） | services/chatPendingQueue.ts · ChatFeed drain · ChatInputBar Queue #n |
| 思考流（D19） | live_reasoning state · AgentLiveActivity 思考折叠 · mcp_react reasoning |
| 长任务监视（D26） | bg_jobs_monitor.py · Supervisor [Monitor] 行 · bgJobMonitor toast |
| 前台转后台（D34） | foreground_shell.py · shell_proc.py · ForegroundShellBar · move_fg_to_background WS |
| Worktree 隔离（D32） | worktree_isolation.py · routes/worktree.py · FooterWorktreeMenu · GET /api/workspace/tree?wt_id= · GET /api/workspace/changes?wt_id= · GET /api/workspace/git（始终主仓，底栏 Branch） · WS enable_worktree / select_worktree / merge_worktree / discard_worktree |
| Cap-D25 定时任务 | scheduled_tasks.py · routes/scheduled_tasks.py · ScheduledTasksBar · scheduledTasksApi.ts |
| D24 诊断 MVP | code_diagnostics.py · builtin diagnostics · DiagnosticsIssuesStrip |
| D36 headless Agent | headless_agent.py · headless_cli.py · routes/agent_run.py |
| D14 Grok CLI | grok_cli_adapter.py · grok-cli in tools_status / engine_router |
| 会话 fork/回滚（D23） | session_fork.py · file_rewind.py · fork/rewind API · Chat 菜单 |
| 跨会话记忆（D16 / B-39 / B-40 / B-45 / FM-12） | cross_session_memory.py · workspace_memory.py search_memory · GET /api/memory/search · Settings Memory 检索 · Files .clutch/memory/MEMORY.md |
| Design 视觉审查（FM-16 / B-49） | DesignHandoffTray design-review-card / design-review-reject |
| 解释器错误卡（FM-17 / B-47） | Chat interpreter-error-card · run_terminal_cmd 返回 Interpreter timeout / Interpreter offline（无 + 预览） |
| 校验失败可读条（FM-18 / B-05） | Chat validation-failure-chat · Overview validation-failure-strip |
| 工具 Hooks（D17） | tool_hooks.py · mcp_react Pre/Post 拦截 |
| 能力包导入（D35） | capability_pack.py · Skills 页 Import/Uninstall |
| Chat 用量（D22 / D9 / Q-USAGE-1） | RightPanel Overview overview-run-usage · sessionUsage.ts · chat_messages._token_patch_turn / stash_turn_usage · http_complete 透传 usage · mcp_react 累计 |
| Chat 模式预设（D27） | permissionApi.ts PERMISSION_MODES · ChatInputBar 权限菜单 · mcp_react explore/plan 硬拦截 |
| 能力↔Chat UI 门禁（D52） | docs/PRODUCT_INTRO.md（capability-ui-table）· scripts/check-capability-ui-table.sh |
| MCP Hub 探测（D38） | mcp_storage.probe_server_by_id · POST /api/mcp/servers/test · McpServerHub Test connection |
| MCP Streamable HTTP（D57） | mcp_client.py HTTP POST · HTTPS 401 → mcp-remote · Hub 通用表单 · docs/mcp-servers/figma.md |
| Chat MCP 徽章（D40） | McpBindingBadge.tsx · agentMcpSummary.ts |
| MCP 真工具名 / 一键 FS（D42∥D44） | AgentManager.tsx Module 4 + catalog tool chips |
| MCP Resources（D43） | mcp_resources.py · Hub Browse/Pin · agent_prompt mcp_resources 层 |
| Chat 变更文件芯片（D47） | components/FilesChangedChips.tsx |
| Chat 计划卡（D2/D49） | components/PlanCardView.tsx · builtin propose_plan · D31 行内批注 |
| 计划批注解析（D31） | plan_revise.py · chat_runner revise payload |
| Chat Todo 卡（D3/D49） | components/TodoCardView.tsx · builtin todo_write |
| Chat 提问卡（D4/D49） | components/QuestionCardView.tsx · builtin ask_user_question |
| Chat 验证报告卡（D5/D50 / B-37） | VerificationReportCardView.tsx · submit_verification · verify_harness.py · verification_report_allowed |
| Chat Diff 摘要卡（D6/D50） | components/DiffSummaryCardView.tsx · builtin submit_diff_summary |
| Chat Agent 卡壳（共享） | components/chatAgentCard.tsx |
| Sidecar 结构化 tool steps（D46） | services/orchestrator/src/tool_steps.py |
| Tool ACI 文件名 → List（B-41） | tool_use_policy.apply_filename_grep_rewrite · tests/test_tool_aci_b41.py |
| Chat 编排拆分（DECISIONS D38 Phase 1） | 编排壳 chat_runner.py · 消息/seal chat_messages.py · WS 信封 chat_ws_events.py · MCP/Plan/Question 门禁 chat_mcp_gates.py（main/chat_runner re-export 兼容） |
| Chat markdown（fence / 路径预览） | components/chatContentRender.tsx · services/workspacePathLinks.ts |
| Coding 附件上传 / 路径 resolve API | services/workspaceApi.ts → POST /api/workspace/attachments · GET /api/workspace/file/resolve；后端 workspace_attachments.py |
| Terminal Orchestra（Lane / OrchestratorBar / 路径 link） | components/terminal-orchestra/（OrchestratorBar.tsx 发图 chip；terminalPathLinkProvider.ts xterm 可点路径） |
| 终端模式 xterm 视图 | components/ChatTerminalView.tsx（无引用遗留；现用 terminal-orchestra/） |
| 对话/终端模式切换状态 | services/workspaceViewMode.ts |
| 工作流 Chat 步骤 / Agent 类型解析 | services/workflowAgentSteps.ts |
| Agent / 工具品牌 Logo | services/brandLogos.ts · components/BrandLogo.tsx · assets/tool-logos/（含 mimo.svg） |
| 右侧面板（Overview/Files/Flow/Changes/Terminal） | components/RightPanel.tsx |
| Terminal 日志子面板 | components/TerminalPanel.tsx |
| 文件预览浮层 | App.tsx（previewFile） |
| Prompt / 错误边界组件 | components/PromptModal.tsx · components/AppErrorBoundary.tsx |
| 模型配置 UI（M4-09） | components/ModelsManager.tsx |
| 主题 Appearance（P2） | components/ThemeManager.tsx |
| 设置模态壳 | components/SystemPreferencesModal.tsx |
| i18n（P2） | components/LanguageContext.tsx |
| Design 模式（D36 · 工作区会话 + 原型交互画布） | components/design/DesignWorkspace.tsx · 出码托盘 components/design/DesignHandoffTray.tsx（入口：PreviewDemo → Coding；D41 确定性导出）· 辅助函数 components/design/designWorkspaceUtils.ts · React Flow 卡片节点 components/design/nodes/ · services/designApi.ts |
| 工作流画布编辑 | components/WorkflowOrchestration.tsx |
| 工作流 JSON 面板（D9） | components/WorkflowJsonPanel.tsx |
| 画布 ↔ compiler 转换（D9） | services/workflowFormat.ts |
| 工作流 Sidecar API 客户端 | services/workflowApi.ts |
| Agent 角色配置 | components/AgentManager.tsx |
| Agent CLI 安装指引与推荐列表 | services/cliInstallGuides.ts · 后端白名单 services/orchestrator/src/tools_status.py · 路由 engine_router.py · 派发目录 terminal_cli_catalog.py（含 mimo-cli；文档清单见 D19） |
| MiMo Code CLI 模型/MCP/Skills 扫描 | services/orchestrator/src/cli_agent_config.py（scan_mimo_models） |
| 内置 Clutch Agent 定义与合并 | services/builtinAgent.ts |
| Agent Registry API | services/agentApi.ts |
| AI 工具连接状态 | components/AiToolsManager.tsx |
| Skills 注册 | components/SkillsRegistry.tsx |
| MCP 配置 | components/McpServerHub.tsx |
| MCP Registry API（P2-02） | services/mcpApi.ts |
| 顶栏 | components/Header.tsx |
| 全局样式 | index.css |
| 类型定义 | types.ts |
| Vite 配置与代理 | vite.config.ts |
| Tauri 壳与 Sidecar 拉起 | src-tauri/ |
| 想改什么 | 去哪里 |
|---|---|
| FastAPI 入口、HTTP/WS 路由 | src/main.py · 模块化路由包 src/routes/ (workspace.py, models.py, settings.py, pty.py, design.py, chat.py) |
| Design 模式设计系统及画布生成服务 | src/design/service.py · 确定性出码 src/design/fidelity_export.py（D41）· 拆分子模块 src/design/ (session_store.py, preview_manager.py, generator.py, thumbnail.py, layout.py, token_usage.py) |
| ClutchState 初始值 | src/state.py |
| 会话元数据持久化（M2-07） | src/run_history.py |
| 会话 messages 持久化（D11） | src/run_state_store.py |
| LangGraph 最小运行时 | src/graph.py |
| Workflow JSON Schema 校验 | src/workflow_validator.py |
| WorkflowCompiler（M1-02） | src/compiler/ |
| Orchestrator 路由（M1-04） | src/orchestrator/routing.py |
| Engine Router（aiEngine / Connect 分流） | src/engine_router.py |
| Agent CLI 探测与白名单 | src/tools_status.py · src/agent_type.py · src/provider_registry.py · src/adapters/cli_adapter.py |
| ShellSession Hybrid Runtime（D25 Step 1） | src/shell_session.py、src/shell_exec_runtime.py、src/hybrid_audit_log.py（HRT-05 JSONL）、src/hybrid_concurrency.py（HRT-08 拒绝+提示）、src/run_debug.py（HRT-06 debug API）、src/claude_hybrid_output_parser.py（含 OutputEvent）、src/runtime_config.py |
| RuntimeStrategy / Provider 注册表 | src/runtime_strategy.py、src/provider_registry.py、src/runtime_registry.py |
| Context Continuity 快照 | src/session_snapshot.py；GET/PUT /api/shell-snapshots/{run_id} · GET /api/shell-snapshots |
| HumanInputKind 载荷 | src/human_input.py |
| agent_task 节点执行 | src/agent_executor.py |
| Agent 持久化与内置 Agent | src/agent_storage.py |
| Agent system prompt 组装（D53 / D68 style） | src/agent_prompt.py · src/agent_skills.py |
| Agent 评测快照 + Agnes live（B-34） | src/agent_eval.py · services/orchestrator/tests/test_agent_eval_b34.py · CLUTCH_AGENT_EVAL_LIVE=1；定义见 specs/core/tasks.md §Agent Harness |
| Agent 消融闸 + trajectory（B-48） | agent_eval.parse_ablation / persist_trajectory · services/orchestrator/tests/test_agent_eval_b48.py · CLUTCH_AGENT_EVAL_ABLATION · runs/archive/eval/ |
末尾 <agent_status>（B-35） |
agent_prompt.format_agent_status / attach_trailing_status · Chat attach 在 _history_with_prefix_and_status；定义见 tasks.md §Agent status |
| 项目规则发现 + Skills 按需（D7） | agent_prompt._load_workspace_rules · read_skill · skills_storage.sync_workspace_skill_mounts |
| 长聊任务态 / 压缩（D8 / B-36 / B-44） | src/task_state.py · compaction.py（L4） · context_layers.py（L1–L3；指针 source=tool truncated=yes） |
| 运行可控（D9 / B-38） | run_control.py · progress_loop.py · mcp_react fuse · Chat Stop/Continue |
| 子任务委派（D10∥D48） | src/subagent_runner.py · delegate_subtask · SubtaskCardView.tsx |
| 后台命令（D11） | src/bg_jobs.py · shell_proc.py · run_terminal_cmd background · BackgroundJobsBar.tsx |
| Git + 网页（D12） | builtin_tools git_*（非 git 仓不挂） / web_fetch · web_fetch_util.py |
| 权限规则（D13） | src/permission_rules.py · settings permission-rules · clear_approvals |
| PM 验收用例包 | runs/verification/pm-acceptance/ |
| 本轮 prompt 组装摘要 API（D53） | GET /api/agents/{id}/prompt-assembly（routes/settings.py） |
| 运行日志 WS 转发 | src/run_log_forwarder.py |
| 工作流状态投影 | src/workflow_projection.py |
| 工作流运行中取消 | src/workflow_cancel.py |
| Terminal 日志格式化与时间戳 | src/terminal_logs.py |
| MCP 工具风险判定 | src/mcp_risk.py |
| MCP ReAct 执行 | src/mcp_react.py |
| 联网搜索（D15） | web_search_util.py · Settings Allow network · builtin_tools |
| Tool-skip nudge（D44 harness） | tool_use_policy.py · mcp_react tool_choice=required retry |
| 交付物意图（需求拆解→kind） | deliverable_intent.py · FE agentActivitySteps classifyDeliverableIntent |
| Chat 产物目录 / 出图出视频（D54） | artifact_layout.py · media_deliverable.py · generate_image/generate_video · .clutch/artifacts/ · .clutch/generated/{images,videos}/ |
| 富读 PDF/图（D33） | rich_read_util.py · read_file in builtin_tools |
| Codex 兼容 apply_patch（增删改移） | src/apply_patch.py |
| 内置虚拟工具服务器 clutch-tools | src/builtin_tools.py（read/list/grep/search_replace/run_terminal_cmd/apply_patch） |
| D21 ignore + strict sandbox | src/ignore_rules.py · preferences_storage strict_sandbox · Settings General toggle |
| Chat Clutch Agent 能力表（D44） | specs/core/clutch-agent-capability-plan.md |
| 凭证来源（CC Switch / 环境变量） | src/credentials/sources.py |
| 工作区 Git 分支探测 | src/workspace.py → get_git_info() |
| Shell 写文件 → Changes | workspace.snapshot_workspace_mtimes / diff_workspace_snapshots · mcp_react._record_file_change |
| LLM Provider Router（M1-08，D4） | src/llm/router.py（默认 agnes-3.0-flash） |
| Agnes 图/视频适配器 | src/adapters/agnes_image_adapter.py · src/adapters/agnes_video_adapter.py |
| LLM HTTP 补全 | src/llm/http_complete.py |
| OpenCode Zen 模型目录 / 保存校验 | src/adapters/opencode_zen_adapter.py |
| 内置模型 Provider 预设（含 OpenCode Zen） | apps/desktop/src/services/modelProviderPresets.ts |
| 模型配置序列化 | src/models_config.py |
| 用户工作流存储 API（M1-09，D5） | src/workflow_storage.py |
| Skills Registry 持久化（P2-01） | src/skills_storage.py、src/skills_scanner.py |
| MCP Registry 持久化（P2-02） | src/mcp_storage.py |
| 用户偏好 / Theme（P2-03） | src/preferences_storage.py |
| CLI Adapter（M3） | src/adapters/ — cli_adapter.py、claude_cli_adapter.py、agy_cli_adapter.py、ollama_adapter.py |
| CLI PTY Session 调研（参考） | docs/research/pty-session.md |
| PTY Session Step 0 实验 | experiments/pty_poc/ |
| TUI 嵌入 Phase 0 实验 | experiments/tui_embed_poc/ |
| 交互 PTY Runtime（终端模式） | services/orchestrator/src/interactive_pty_runtime.py |
| Video Core（M5） | src/video_core/ — config.py、env.py、pipeline.py、renderer.py |
| 依赖与 pytest 配置 | pyproject.toml |
| 想改什么 | 去哪里 |
|---|---|
| 前后端共享 TS 类型 | packages/shared-types/index.ts |
| Workflow JSON Schema | workflows/workflow.schema.json |
| 内置模板（只读） | workflows/*.json |
| 用户工作流（读写，D5） | Tauri 应用数据目录 workflows/ |
| 可选导出到项目 | .clutch/workflows/（导入/导出，非默认） |
| Agent / Evaluator 配置 UI | components/AgentManager.tsx |