0.写在最前面
我是谁？
我是墨染柒DarkSeven，一个高二在读高中生。有梦想，有鬼点子。仓库堆积如山，实现没几个，因为没有时间。我是比较早接触到TRAE 国内版的一群人（有个账号很老了），我的第一个项目就是从TRAE IDE国内版出来的，并且现在偶尔还有一点点更新。
从我上一年级开始，家里就有一台电脑可以供我学习。直到上了高中，尽管中途出现了很多不太如意的事情，但是我也是坚持了下来，没有嘎巴一下无影无踪。虽然说我们家并不是很支持我搞这些（他们其实也不咋懂我在干什么），我的附近的人（主要是同学）一天到晚谈论的也是王者和平三角洲暗区等等所谓“游戏大作”，在班里我基本算是插不上什么话，而且班上的人大部分看到我也并不是很友善（甚至说的过分一点，看我像看怪物看嘉豪看网上那些所谓打开CMD扫个盘就敢口称“黑客“的那种人一样）。他们不知道什么叫Vibe Coding，只知道看着时代的变化，同时嘲讽着追逐时代潮流的人。感谢TRAE官方，给了我这样的一个机会，能够走出我的圈子，能够暂时不去想作业，不去想学校里面小团体们的勾心斗角，能够专注于我想做的事情。
我想说的就这么多了。
1. Demo 简介
是什么： Orcha 是一个基于命令行的自动化编码操作系统，通过飞书 IM 长连接接入，用户在聊天窗口里 @Orcha 一句话发起编码任务，系统自动拆解、执行、测试、审核，把改动 commit 并推到 Git 新分支。后端为 Rust（Cargo workspace，7 个 crate），飞书接入层为 TypeScript 独立进程。Web UI 仅作为开发期观测面板（未检测），初赛交付主体是飞书 IM 交互。
面向谁： 中小团队的技术负责人、独立开发者、开源项目维护者——需要频繁处理"小而杂"的编码任务，但不想在工具切换和重复执行上浪费时间的人。
主要功能：
-
飞书一句话触发 → AI 自主闭环 — @Orcha 发任务后，AI 自主调度 6 个 Sub-Agent（Observer → Planner → Worker → Tester → Reviewer → Exit），由 LLM 决定每一步调谁、何时结束、失败怎么重试（最多 10 轮 + 每步 3 次重试）。任务进行中飞书卡片持续 patch 更新进度（
启动 → 
观察中 → 
规划中 → 
写代码 → 
完成）。 -
写文件 / 跑命令 / 删文件前推飞书审批卡片 — Worker 在执行敏感操作前，经 GatewayApprovalHook 推审批卡片到飞书，用户点【批准】/【拒绝】按钮，回调走
card.action.trigger事件回到 Gateway。三类操作有独立白名单，未配置即 fail-closed，超时 30 分钟自动拒绝。 -
GitWorktree 隔离 + 自动落分支 — 每个任务在
git worktree add创建的独立工作区改代码，原 repo 工作区不被污染。任务成功后由 LLM 生成 commit message 和orcha/{slug}分支名，自动 commit 并把改动持久化到原 repo 的新分支（worktree 清理后分支与 commit 不丢）。
截图位置：
【截图 1 - 飞书群 @Orcha 发起任务 + 卡片启动状态】
【截图 2 - 任务执行中卡片 patch 更新（含审批卡片按钮）】
【截图 3 - 任务完成卡片，显示分支名 + commit hash + commit message】
2. Demo 创作思路
灵感来源： 灵感来自交响乐团指挥——Orchestra。复杂乐章需要指挥协调不同乐手配合完成；同样，复杂编码任务也需要一个"指挥"来调度多个 AI Sub-Agent 分工协作，并通过循环验证不断修正。这就是 Cycleround 循环工作流的核心思路。
想解决的问题： 现有 AI 编码工具大多是"你说一句，我改一行"的被动模式，遇到复杂需求时开发者仍需自己拆解步骤、协调工具、反复验证。一个"小需求"也要经历：手动拆任务 → 打开 IDE → 写代码 → 跑测试 → 发现问题 → 再改再测 → 切回 IM 同步进度，实际写代码时间可能只占总时长的 30%。Orcha 想让开发者只需一句话描述目标，系统自动拆解、执行、验证、循环优化，直到真正完成。
为什么做这个方向： 判断与取舍有三点：
-
聚焦 IM 交互而非 Web UI：开发者真正的工作入口是 IM（飞书 / Slack），不是另一个浏览器标签页。Roadmap 里明确 M5 Web UI 不纳入初赛验收，把所有精力压在 M7 IM 接入与智能守护上。
-
AI 驱动调度而非硬编码流水线：早期确定性 Cycleround（Observer→Planner→…→Fixer 固定顺序）只能跑 demo，遇到真实 repo 就僵化。M7 P0 把调度权交给 LLM（
AiDrivenCycleround+decide_next_agenttool calling），让 AI 自己决定下一步调谁。 -
声明式写边界 + 人工审批双保险：让 LLM 自由写真实 repo 风险太高。M4 设计了 7 层写边界（路径规范化 / 写白名单 / action 权限 / 读保护 / 危险路径黑名单 / diff 范围校验 / workspace 隔离），M7 P1 又叠加飞书审批卡片人工确认，敏感操作必须人点【批准】才执行。
3. Demo 体验地址
已发布v0.1.1-beta 公测版，可通过以下链接下载：
1.GitHub Release链接： Release Orcha v0.1.1-beta · Ink-dark/orcha
- 国内蓝奏云优享版加速下载镜像：蓝奏云优享版-Orcha
4. TRAE 实践过程
4.1 完整开发流程
整个 Orcha 项目从创意到初赛交付，全程在 TRAE IDE 中完成，关键节点如下：
| 阶段 | 里程碑 | TRAE 完成内容 |
| :— | :— | :— |
| 创意 | 报名 | 用 TRAE Work 生成完整创意产物 HTML（含系统架构、核心概念、网关规范、调度机制、安全策略、开发路线图） |
| M0-M3 | MVP 闭环 | 用 TRAE IDE 搭 Cargo workspace 骨架（7 crate）、数据模型（serde + schemars 15 个模型）、确定性 Cycleround（Observer/Planner/Worker/Tester/Reviewer/Fixer）、3 个 golden tasks 端到端验证 |
| M4 | 写边界 | 用 TRAE IDE 实现 path_guard.rs（路径规范化 + 逃逸防御）、plan.rs（Plan schema + search-and-replace 编辑引擎）、改造 LlmWorker / LlmReviewer 越界检查、7 条端到端测试 |
| M4 | 真实编辑能力 | 用 TRAE IDE 升级 Worker prompt 支持 steps 格式（edit/create/delete action）、新增 WorkerStep / WorkerOutput / parse_worker_output_with_steps、apply_step 实现 search 唯一匹配 + unified diff 生成 |
| M7 P0 | AI 驱动调度 | 用 TRAE IDE 实现 ai_cycleround.rs（把调度权交给 LLM via decide_next_agent tool calling）、8 单元测试、CLI 集成 orcha fix --ai --llm |
| M7 P1 | 审批管理 | 用 TRAE IDE 设计 [approval] 三类白名单（write/command/delete）、GatewayApprovalHook fail-closed 逻辑、飞书 card.action.trigger 事件处理、卡片状态 patch |
| M7 P1 | LLM 重试降级 | 用 TRAE IDE 给 orcha-llm/client.rs 加 max_retries / retry_base_ms、429/5xx 指数退避（1s→2s→4s，最多 3 次）、config.rs 同步字段 |
| 联调 | 真实仓库冒烟 | 用 TRAE IDE 在 bit-torch/adaptergit 真实仓库跑端到端冒烟（reverse_string 任务 2 轮成功），修复 3 个阻塞 bug：LLM JSON 输出带前导文本、Windows CRLF 行尾不匹配、Windows UNC 路径解析失败 |
| 联调 | 飞书端到端 | 用 TRAE IDE 完成飞书联调：鉴权白名单 user = "*"、卡片 schema 1.0 顶层 elements、订阅 card.action.trigger、WorkspaceConfig + GitWorktree 集成、心跳线程每 30s 推 CardUpdate |
| 验收 | 端到端任务 | 任务 T-6bbd2024 7 轮闭环成功，自动 commit 到分支 orcha/add-reverse-string（commit ed4fc73），commit message feat(utils): add reverse_string function 由 LLM 生成，作者 Orcha Bot |
4.2 开发关键步骤截图
截图位置（3 张）：
【截图 1 - TRAE Work 中ai_cycleround.rs实现 AI 驱动调度的代码视图】
【截图 2、3 - TRAE IDE 中跑cargo test全绿（orcha-llm 25 测试 / orcha-core 217 测试 / clippy 0 警告）的终端输出】
4.3 关键任务对话 Session ID
以下 Session ID 在 TRAE 中可验证作品由 TRAE 开发完成：
- Session ID：
2913059151306983:08f178ae65b6a17bd4acc4b4fa45ca88_6a48d0bb0d1d40504ecb3fbf.6a48d0bf688d362f626bb23f.6a48d0bb0d1d40504ecb3fc0:TRAE Work CN.0.1.30.no_sid.no_ppe.T(2026/7/4 17:26:12)
-
覆盖内容：开始轮次对话，进行长线任务规划，将原 README Section 8 的 4 行 Phase 罗列替换为可验证的 M0–M8 Milestone 体系 ，并新增 Section 9 验收追踪约定。
-
关键产物：
README.md（后拆分成docs/DEPLOYMENT_TOPOLOGY.md、docs/ROADMAP.md、docs/SPEC.md三个主心骨文件。
- Session ID：
2913059151306983:e1f2281ae7c50723cf6cff532b1b20c7_6a4b5cb87d466d3b8b137eab.6a4b5cb87d466d3b8b137eae.6a4b5cb87d466d3b8b137eac:TRAE Work CN.0.1.30.no_sid.no_ppe.T(2026/7/6 15:43:52)
-
覆盖内容：分析 Orcha 当前编码 Agent 距离可用状态还缺哪些能力，按优先级梳理 8 项缺失（tool calling / 文件编辑 / agent loop / 上下文预算 / LLM 重试 / 写边界等），并把 M4 写入 ROADMAP（含 P0/P1 优先级与 7 层写边界设计）
-
关键产物：
docs/ROADMAP.mdM4 章节、后续 M4-M7 实施的优先级基线
- Session ID：2913059151306983:3c8cc7082547b5deeaef46f9d1b3b8b8_6a4b504c7d466d3b8b137c46.6a4b58457d466d3b8b137d79.6a4b58457d466d3b8b137d77:TRAE Work CN.0.1.30.no_sid.no_ppe.T(2026/7/6 15:24:53)
- 覆盖内容：完成了 M4 里程碑的核心 P0 交付物和 P1 审计日志：
M4 P0 完成项
1. Tool Calling 机制（Tool Calling）
变更文件：
client.rs — ChatMessage 新增 tool_calls/tool_call_id 字段；新增 ToolDefinition、ChatResponse、ToolCallRequest 类型；LlmClient trait 新增 chat_with_tools 方法（默认降级到 chat）；OpenAiCompatibleClient 完整实现 function calling
tools.rs — 新建，含 4 个工具：read_file（带行号+读保护）、grep（子串搜索+200 条截断）、glob（支持 **/*/?）、list_dir（标文件/目录图标）；agent loop 核心函数 run_agent_loop（最大 5 轮工具调用）
prompt.rs — Planner/Worker prompt 升级：告知 LLM 可用工具，要求先探索 workspace 再输出 JSON
llm_agents.rs — LlmPlanner::run_at 和 LlmWorker::run_at 从单次 chat() 改为 run_agent_loop，LLM 可多轮调工具直到产出最终答案
2.Git Worktree 隔离（Git Worktree Isolation）
变更文件：
sandbox.rs — 新增 GitWorktree 结构：构造时 git worktree add --detach <temp_dir> 创建隔离工作区，drop 时 git worktree remove --force 清理。原 repo 完全不受污染
3.审计日志（Audit Logging）
变更文件：
audit.rs — 新建：AuditLogger（JSONL 格式，线程安全）记录所有文件操作的 timestamp/agent/path/action/canonical_path/approved/reason。提供 NoopAuditLogger 用于不启审计的路径。已在 tools.rs 的 read_file/grep/list_dir 中接入
5. 通过的社区报名帖链接
学习工作-造个新解法 | Orcha —— 让 AI 自己闭环的编码副手
报名帖原文件已存于仓库
orcha-registration-post.md，标题为「学习工作-造个新解法 | Orcha —— 让 AI 自己闭环的编码副手」，标签 #学习工作。
ps：经验总结与开发心得
踩过的坑（已记录在 project_memory）：
-
LLM JSON 输出带前导文本：DeepSeek 偶尔在 JSON 前输出解释性文字导致解析失败。修复方式：新增
extract_json_object兜底提取第一个{...}块。 -
Windows CRLF 行尾不匹配：search-and-replace 在 Windows 上经常匹配失败。修复方式：
apply_edit匹配前归一化为 LF，写入时保留原始行尾风格。 -
Windows UNC 路径解析失败：
file:///\?:..类 URL 解析炸了。修复方式：Reviewer /extract_files先剥file:///再剥file://前缀。 -
飞书卡片 230099 错误：卡片更新失败。修复方式：所有卡片（CardUpdate / ApprovalRequest / ApprovalResult）统一用 schema 1.0 顶层
elements字段。 -
空目录执行 MaxRoundsExceeded：未配
[workspace]时 LLM 在空目录里瞎转。修复方式：config.toml强制要求[workspace] repo+worktree = true，queue.rs用GitWorktree隔离执行。 -
审批粒度不足：早期复用
auth.whitelist导致审批粒度不够。修复方式：拆出独立[approval]段，write / command / delete 三类独立白名单，fail-closed 语义。
架构心得：
-
Rust 业务层 + TS UI/接入层的分层在飞书场景下很舒服：Rust 吃 LLM 调用 / 状态机 / Git 操作的复杂度，TS 吃飞书 SDK 的 WebSocket 长连接 / 卡片渲染，IPC 用 JSON line 协议解耦。
-
GitWorktree 是 LLM 改真实 repo 的必备隔离：即便 LLM 乱写，原 repo 工作区不被污染，回滚只需
git worktree remove。任务成功后 commit 写入原 repo 对象库，worktree 清理后分支与 commit 都不丢。 -
AI 驱动调度比硬编码流水线灵活得多：早期确定性 Cycleround 只能跑 demo，换成
AiDrivenCycleround后 LLM 能根据上一轮 Tester 的 stderr 决定是回到 Worker 修代码还是直接 Exit，体感更像"一个真人在改代码"。
最后的最后
Git 提交与 TRAE Session 时间对齐
| Session | TRAE 时间 | 对应提交 | Git 时间 | 内容 |
|---|---|---|---|---|
| 规划阶段 | 2026-07-04 17:26 | 0a267ee |
17:18 (+0800) | README 里程碑体系 |
| 规划阶段 | 2026-07-04 17:26 | 20e1ea7 |
17:58 (+0800) | 上传报名文件 |
| M4 实施 | 2026-07-06 15:24 | 513d31c |
15:47 (+0800) | M4 写边界安全 |
| M4 实施 | 2026-07-06 15:24 | 8569bec |
15:48 (+0800) | M4 Tool Calling |
| M4 实施 | 2026-07-06 15:24 | 0e8a7d5 |
15:48 (+0800) | M4 GitWorktree + 审计 |
| M7 P0 | 2026-07-06 15:43 | 9f42aed |
16:42 (+0800) | M7 AI 驱动调度 |
| M7 P1 | 2026-07-06 15:43 | e6b82c4 |
16:53 (+0800) | M7 人工审批 Hook |
"AI驱动调度而非硬编码流水线"这个架构决策非常关键，把调度权交给LLM让它根据Tester的stderr自主决定是回Worker修代码还是Exit，这比固定顺序的pipeline灵活太多了。