baa-conductor

T-S051.md

 1# Task T-S051：代码文件直读映射
 2
 3## 状态
 4
 5- 当前状态：`已完成`
 6- 规模预估：`S`
 7- 依赖任务：无
 8- 建议执行者：`Codex` 或 `Claude`
 9
10## 直接给对话的提示词
11
12读 `/Users/george/code/baa-conductor/tasks/T-S051.md` 任务文档，完成开发任务。
13
14## 当前基线
15
16- 仓库：`/Users/george/code/baa-conductor`
17- 分支基线：`main`
18- 提交：`4663817`
19
20## 分支与 worktree（强制）
21
22- 分支名：`feat/code-file-serving`
23- worktree 路径：`/Users/george/code/baa-conductor-code-file-serving`
24
25开工步骤：
26
271. `cd /Users/george/code/baa-conductor`
282. `git worktree add ../baa-conductor-code-file-serving -b feat/code-file-serving main`
293. `cd ../baa-conductor-code-file-serving`
30
31完成后提交与推送（由执行者完成，不要合并）：
32
331. 在 worktree 里提交所有变更（包括更新后的任务文档）
342. `git push -u origin feat/code-file-serving`
35
36## 目标
37
38conductor 的 `/code/` 路由直接 serve 磁盘上的代码文件，AI 通过 URL 读取任意源文件。
39
40## 必须完成
41
42### 1. 路由实现
43
44- `/code/:path*` 路由，映射到可配置的根目录（默认 `/Users/george/code/`）
45- Content-Type 统一 `text/plain; charset=utf-8`
46- 文件不存在返回 404
47- 根目录可通过环境变量配置：`BAA_CODE_ROOT_DIR`
48
49### 2. 安全限制
50
51- 路径中不允许 `..`（防止目录遍历）
52- 排除敏感文件：`.env`、`.credentials`、`.git/objects`
53- 排除二进制文件（可选，根据扩展名判断）
54- 不允许访问配置的根目录之外的路径
55
56### 3. 目录列表（可选）
57
58- 如果请求的是目录，返回文件列表（纯文本，每行一个文件名）
59- 或者返回 JSON 数组
60
61## 允许修改的目录
62
63- `/Users/george/code/baa-conductor/apps/conductor-daemon/src/local-api.ts`
64- `/Users/george/code/baa-conductor/apps/conductor-daemon/src/index.ts`（配置项）
65
66## 验收标准
67
68- `curl http://100.71.210.78:4317/code/baa-conductor/package.json` 返回文件内容
69- `curl http://100.71.210.78:4317/code/baa-conductor/.env` 返回 403 或 404
70- 路径遍历攻击 `../../../etc/passwd` 返回 403 或 404
71- 不存在的文件返回 404
72
73## 执行记录
74
75> 以下内容由执行任务的 AI 填写，创建任务时留空。
76
77### 开始执行
78
79- 执行者：`Codex`
80- 开始时间：`2026-03-29 23:20:00 CST`
81- 状态变更：`待开始` → `进行中`
82
83### 完成摘要
84
85- 完成时间：`2026-03-29 23:49:38 CST`
86- 状态变更：`进行中` → `已完成`
87- 修改了哪些文件：`apps/conductor-daemon/src/local-api.ts`、`apps/conductor-daemon/src/index.ts`、`apps/conductor-daemon/src/index.test.js`
88- 核心实现思路：新增 `/code/:code_path*` 只读路由；将 `BAA_CODE_ROOT_DIR` 解析进 runtime 配置并透传给 local API；请求时先约束 `..`、绝对路径和敏感路径，再通过 `realpath` 校验目标仍位于根目录内；目录请求返回过滤后的纯文本文件列表；文件请求统一以 `text/plain; charset=utf-8` 返回；按扩展名拒绝常见二进制文件。
89- 跑了哪些测试：`pnpm install --frozen-lockfile`；`pnpm test`（`apps/conductor-daemon`，57/57 通过）
90
91### 执行过程中遇到的问题
92
93- 新建 worktree 后缺少 `node_modules`，先在 worktree 根目录执行 `pnpm install --frozen-lockfile` 后再构建测试。
94- 仓库自带的 `node` shim 没声明 `readdirSync`/`realpathSync`/`statSync`/`extname`/`relative`，在允许修改的源码文件内通过 namespace import + 类型断言兼容了现有 TypeScript 构建。
95
96### 剩余风险
97
98- 二进制文件过滤目前基于扩展名，未做内容探测；无扩展名的二进制文件理论上仍可能被当作文本读取。
99- 遍历型 URL 在进入路由前可能被 WHATWG URL 规范化为不存在路径，因此部分攻击请求会返回 `404` 而不是 `403`；这仍满足当前验收标准。