开发工作流

本页面向准备修改 PkuClaw 代码或 runtime 文件的开发者。

代码归属

pkuclaw/
  core/         # run orchestration、LoopManager、Store、共享模型
  runtime/      # runtime 文件 loader：config/events/prompts/skills
  agents/       # AgentWrapper、Codex provider、sink、artifact
  channels/     # 平台 adapter：事件转换、流式展示、卡片详情
  notify_queue/ # daemon 文件通知队列 worker
scripts/        # outbox 脚本 thin clients

不要新增顶层 runtime_*.py、code_agents/ 或业务 connector 包。新逻辑应放入对应层。

Prompt 修改

Prompt 文案优先修改：

configs/runtime/prompts.json

而不是硬编码进 pkuclaw/agents/wrapper.py。

修改后至少检查：

realtime prompt 不包含 loop-only 信息；
realtime prompt 不包含通知脚本；
loop prompt 不复用 realtime 回复规则；
loop prompt 通过 Skill Catalog / Suggested Skills 暴露 Channel Outbox Skill；
Skill Catalog 来自 configs/runtime/skills.json。

Runtime 修改

Runtime 文件是普通可编辑文件：

configs/runtime/runtime.example.json
configs/runtime/runtime.json  # local, ignored
configs/runtime/events.json
configs/runtime/prompts.json
configs/runtime/skills.json
configs/runtime/skills/**

runtime.example.json 是可提交模板；本地复制为 runtime.json 后再填写 loop 通知目标。不要提交真实 runtime.json，它可能包含 open_id/chat_id 等本地 channel 目标。

修改时建议保持：

JSON 格式稳定；
schema_version 不乱改；
真实通知目标、凭据和隐私数据不要进入示例或文档；
loop 行为默认静默，重要变化才通知。

文档维护地图

文档以 docs-site 为主，根 README 只保留快速入口：

根目录 README.md：项目简介、快速安装和文档入口；
docs-site/content/docs/user-guide**：使用者安装、配置和日常运行文档；
docs-site/content/docs/developer-guide**：架构、runtime、skill、开发流程和参考文档；
ARCHITECTURE.md：仓库级架构说明；如果内容继续扩展，优先同步或迁移到文档站；
configs/runtime/skills/**：runtime skill 正文的 source of truth，文档站只解释目录、边界和索引。

测试命令

python -m compileall pkuclaw scripts
python -m unittest discover

文档站修改还应运行：

cd docs-site
npm ci
npm run build

开发 workflow

明确边界：判断修改属于 core、runtime、agents、channels 还是 scripts。
小步提交：先改最小闭环，避免同时重构多个层。
本地验证：运行 Python 检查；文档改动运行 Next.js/Fumadocs build。
更新文档：行为变更同步更新 Fumadocs 文档；runtime 文件格式变化同步更新配置参考、Runtime 设计和 Skill Catalog 页面。