# Research Workspace

用于开源项目调研、研究和试验性开发。每个 project 都是一个研究主题，其中可以包含多个源码仓库和大量文档。

## 开始工作

1. 从 `PROJECTS.toml` 找到目标项目，只读取该项目的条目和相关文件；接续工作先读 `worktrees/<name>/README.md`。
2. 新建项目、增删仓库、形成阶段总结或归档时，先读 [.agents/workflow.md](.agents/workflow.md)，按其中的元数据约定收尾。
3. 项目名称由用户指定；缺少名称时先询问，其他独立工作可以继续。名称使用小写字母、数字和连字符；需要改写用户名称时先确认。当前 `harness` 是研究项目名，其下的工具名称是仓库名。

## 文件落点

- `worktrees/<name>/README.md`：研究问题、当前进度、证据入口、下一步。
- `worktrees/<name>/repos/<repo>/`：独立 Git clone 或 Git worktree；`worktrees/` 是容器名称，不强制使用 `git worktree`。
- `worktrees/<name>/notes/`：过程记录、资料摘记、实验日志；`experiments/`：试验代码和可复现步骤。
- `docs/<name>/`：经过核对的阶段总结、结论和建议。
- `PROJECTS.toml`：项目名、目的、归档状态、更新时间、仓库来源及研究基线、正式文档路径的唯一登记处。
- `.agents/`：工作区公共流程和工具；项目专属信息放回项目目录。

## 研究与修改

- 一次只处理目标项目。进入源码仓库后读取它适用的 `AGENTS.md`，修改前核对 Git 状态，保留已有工作。
- 分析代码时，目标仓库有 `.codegraph` 则优先用 CodeGraph 定位，再读当前源码核验；索引不可用或过期时说明后使用源码检索。
- 结论标明来源及版本，区分已核验事实、推断和待验证事项。实验记录命令、环境、实际结果；未运行的步骤写明“未运行”。
- 创建项目、更新项目文档、修改试验或仓库配置后，同步相关元数据与 `last_update`（Asia/Shanghai 日期）；只读查看不刷新日期。
- 只有用户明确要求“归档”或“设为不活跃”时，才设 `archived = true`；保留原文件。接续已归档项目时先明确是否恢复活跃状态。
- 公共约定变化时同步 README 和流程说明；收尾执行 `python3.14 .agents/scripts/validate.py`，涉及仓库落地或基线变化时加 `--checkouts`。