Roadmap: v0.1 seed → agent-native ResearchThread #2

目的

把当前 M1–M3 / v0.1 seed 候选版本收口，并明确后续从 local-first research memory workspace 走向 agent-native research memory layer 的发展路径。

核心原则不变：文件是资产，UI 是视图，Agent 是受控操作层。 北极星指标是：一条工作线搁置一段时间后，从重新打开 ResearchThread 到重新理解“当时在做什么、卡在哪里、下一步是什么”的时间。

0. 当前基线：先完成 PR #1 收口

PR #1 已完成上一轮大部分审查修订：CSP、CI、.trash 软删除、README/平台说明、提交邮箱等均已处理；最新 CI 已可重复执行 npm ci → npm test → npm run build。

合并前仍需处理：

• 修复 src/storage/weekly.ts::diffDays() 的月份偏移 bug：Date.UTC(year, month, day) 的 month 是 0-based；当前直接传入 YYYY-MM-DD 中的 1–12，会使滞留天数跨月计算产生偏差。补一个直接针对 diffDays/stale threshold 的跨月、跨年测试。
• 顺手修复周报 create_task 在无法解析 task ref 时留下尾部 · 的格式问题。
• 清理测试中的重复 event key 和 project.id ? space.id : space.id 这类无意义表达，避免未来审阅噪音。
• CI 再次全绿。
• 完成 clean Windows 环境验证：首装、无 git、单实例、重启数据保留、覆盖升级、卸载重装、快照恢复。
• 额外做两项数据安全验证：① Obsidian 同时修改正在编辑的 task；② Task Manager 强制结束进程后重启，确认冲突/原子恢复正常。
• 合并 PR feat: M1-M3 application + seed-release hardening (Windows x64, first code sync) #1 后打 v0.1.0-seed tag，并发布 installer + SHA-256 + seed manual。

.trash 后续注意

当前软删除已保证内容不被物理删除，但 .trash/ 是扁平目录，原始 project/path 主要依赖 activity log 才能精确追溯，而 activity log 是 best-effort。后续应考虑：

• trash 条目保存原始路径元数据，或按原始相对路径保存；
• 增加最小“恢复”入口；
• 暂不自动清理 .trash，在有明确 retention 规则前宁可占空间不要误删。

1. v0.1 seed：先验证“能不能找回研究现场”

不要马上继续堆 UI。先让自己 + 3–5 个种子用户真实使用。

重点收集的不是“还想要什么功能”，而是：

• 哪些时候打开项目后仍不知道上次做到哪里；
• 哪些 next action / context / weekly 信息没有帮助恢复现场；
• 哪些操作仍需要回到文件系统或 Obsidian 才能完成；
• 从打开项目到理解现场大约需要多久（time-to-context）；
• 外部编辑、异常退出、删除恢复是否真的可靠。

建议先隐藏/默认关闭当前 placeholder Agent 页面，等 2a 真正可用后再公开；“插件”页面目前实质是 feature flags，不要演化成插件市场。

Repo polish（单独小 PR）

• 添加 LICENSE（无特殊商业约束时 MIT 即可；如需要明确专利授权可选 Apache-2.0）。
• 添加 topics：research / local-first / tauri / research-workflow / ai-agent / markdown / knowledge-management。
• README 放 1 张真实主界面截图。
• 添加 CI badge + Release link。
• 配置 ruleset/branch protection：test-and-build 为 required check，而不是只在文档里约定。
• 合并后自动删除 feature branch。
• 暂时不做 CONTRIBUTING / issue templates / Wiki / Discussions，等真正有外部用户再补。

2. Phase 2a-lite：只做最小 Ask Agent

目标不是做聊天软件，而是第一次验证“ResearchThread 的上下文能否被 agent 正确利用”。

最小链路：

选中 task → 输入一个问题 → task archive + project map 组成 prompt → Claude/Codex 只读分析 → 展示结果 → 用户决定是否 append 为 agent context entry

• buildProjectMap()：空间→项目→任务的紧凑快照，doing/star/next 优先。
• StructuredAgentRunner：Claude/Codex headless、超时、取消、版本探测、JSONL 容错。
• 默认 read-only；2a 不让 agent 改项目状态。
• agent 输出写回时只能追加 author=agent 条目，不覆写人的既有上下文。
• activity log 正确记录 actor=agent。

做到这里就停止扩充 chat UI，马上进入 MCP。

3. Phase 2b：MCP Server —— 真正的技术转折点

这是 ResearchThread 从“研究任务管理器”变成“研究记忆层”的关键阶段。

建议工具面：

• 只读：get_project_map, get_task, query_activity, search
• 非破坏写：create_space, create_project, create_task, set_status, set_star, set_next, append_context_entry, write_ai_summary
• 破坏操作：不要直接暴露“agent 传 confirmed=true 就删除”的模型。

破坏性操作必须改成 UI confirmation

推荐：

agent request_delete(task) → ResearchThread 生成 pending destructive action → 用户 UI 确认 → app 真正 trash/delete

确认权必须属于用户/UI，不属于 agent 自己声称“已确认”。

其他验收：

• NodeFsAdapter 从 tests 迁为正式共享适配器。
• MCP 与 UI 同时写同一文件时无数据丢失。
• MCP 写入正确归类为 actor=agent，不能被 watcher 记成 external。
• .mcp.json 为 Claude Code 提供项目级零配置接入；Codex 提供显式注册命令。
• MCP 工具面物理上不存在“覆写人写上下文”的接口。

4. Phase 2c：自然语言 → 项目状态

这是第一个真正有产品差异化的 demo。

目标示例：

“Reviewer 2 要求补自由能计算，原来的重投稿先暂停。”

ResearchThread 能安全地完成：

• 当前 task → hold；
• 创建“自由能计算” task；
• append 转折 context；
• 更新 next action；
• activity log 全量留痕；
• agent session 结束自动 git snapshot/commit；
• 任何破坏性动作仍需 UI 确认。

然后再做 inbox 批量自然语言归位和简化版对话面板。

5. Phase 2d：Automatic Research Memory

优先级建议：re-entry brief > 日报 > 周报叙事。

最有价值的自动能力不是“每天发摘要”，而是重新打开一个沉睡项目时直接告诉用户：

你上次停在这里。

建议顺序：

• Project re-entry brief：最近活动、上次决策、当前 doing/star、未完成 next、距离上次更新多久。
• deterministic daily/weekly skeleton：无模型也必须能生成。
• LLM 只负责在骨架上补判断/叙事，不成为事实源。
• 错过调度时启动补跑，不引入常驻服务。

6. 长期必须守住的工程边界

数据完整性

• 所有 app 写入继续走事务写；禁止 UI 直接触 fs。
• 外部修改冲突不能静默覆盖。
• 文件树/frontmatter 是用户资产，破坏性 schema 变化必须有迁移 + 回滚方案。
• .trash 和 git 是安全网，不因“有 agent”而降低数据保护。

安全

当前 renderer 已有 CSP，但 shell capability 仍然非常高权限：cmd / powershell / node / npm / claude / codex / git 都允许任意 args。后续任何 agent/markdown/CLI 输出进入 HTML 前都必须坚持 escape-first。

• CSP 禁止退回 null。
• 不引入 script-src 'unsafe-inline' / 'unsafe-eval'，除非有明确、审计过的必要性。
• 每增加一个 HTML renderer 入口都做 XSS 审查。
• 在 2a/2b 时重新审计 shell allowlist；能不用 cmd/powershell/node/npm 直接暴露就收窄。
• CI 只覆盖 Node/TS 层；Tauri/NSIS 安全与运行仍必须保留手工 release gate。

隐私

“local-first”不等于“AI 内容永不离开本机”。当用户主动调用 Claude/Codex 等外部 CLI 时，发送给 agent 的 context 会受对应服务条款约束。后续 Agent 功能上线前必须在 UI/seed manual 中清楚提示这一点。

Activity / provenance

必须始终能回答：

• 谁改了？app / agent / external
• 改了什么？
• 何时改？
• 能否回滚？

Agent 能力越强，这条要求越重要。

7. 暂时明确不做

除非真实用户反馈证明必要，否则继续拒绝：

• 甘特图 / 任务依赖图 / Calendar；
• 知识图谱；
• 多人协作；
• 云同步；
• 插件市场；
• 复杂 Markdown 编辑器；
• 真 PTY terminal 深度增强；
• 模型 marketplace / API key 管理；
• 自动更新 / 安装签名 / macOS 发布（Windows seed 稳定后再做）。

ResearchThread 不应变成 Notion + Obsidian + Linear + Chatbot 的拼接体。

建议版本节奏

• v0.1.0-seed：M1–M3 + 数据安全 + Windows seed release。
• v0.1.x：只修真实使用中的可靠性/UX bug，不扩产品边界。
• v0.2.0：2a-lite + MCP + 第一条 natural-language state update 跑通；这才是产品差异化版本。
• 后续：re-entry brief / automatic memory，根据 seed 用户的 time-to-context 反馈决定优先级。

这个 issue 作为长期 roadmap/guardrail；具体实现仍建议拆成小 PR，每个 PR 只解决一个阶段，不在 seed release PR 中继续夹带新功能。