mirror of https://github.com/Narcooo/inkos.git synced 2026-08-29 07:14:24 +08:00

Files

T

fanghanjun c21e2995e2 docs: recreate CLAUDE.md with pi-agent tool design rules

Key additions:
- schema 即文档: TypeBox description directly informs the LLM
- Union+Literal for enums: model sees const constraints in JSON Schema
- No hardcoded pipeline params
- Return values must be actionable

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

2026-04-15 21:57:00 -07:00

3.8 KiB

Raw Permalink Blame History

InkOS

AI 长篇小说写作平台。monorepo: packages/core（运行时）、packages/cli（TUI）、packages/studio（Web UI / Hono + Vite）。

常用命令

pnpm dev              # 从根目录启动！core tsc --watch + studio Vite HMR + API server
pnpm build            # 全量构建
pnpm test             # vitest 全仓测试
pnpm --filter @actalk/inkos-core build     # 改了 core 后必须重建（或用 pnpm dev 自动 watch）

设计文档

文档	范围	何时读
`docs/infra/studio-state-management.md`	Studio Zustand store 架构、slice 约定、目录结构	修改 `packages/studio/src/store/` 时
`docs/infra/studio-routing-and-session.md`	URL hash 路由 + 消息隔离 + pi-ai/pi-agent 集成	修改路由、session、LLM provider 时
`docs/infra/studio-service-management.md`	服务商管理页设计	修改 ConfigView / 服务商配置时
`docs/plans/2026-04-15-sub-agent-params-alignment.md`	sub_agent 工具参数对齐设计	修改 agent-tools.ts / sub_agent 工具时

工作规范

不要推测错误 — 遇到报错先读完整错误信息，定位根因后再修，不凭猜测改代码
原子化提交 — 每个 commit 只做一件事，功能和修复分开提交；不要把不相关的改动塞进同一个 commit
每步都跑测试 — 每个 task 完成后必须 pnpm test 全量通过，不能攒到最后才跑
防止 maxTokens 回归 — 替换 LLM provider 时必须确认 maxTokens 参数正确传递，不能丢失或硬编码；写测试验证

pi-agent 工具设计规范

修改 packages/core/src/agent/agent-tools.ts 时必须遵守：

schema 即文档 — TypeBox schema 的 description 直接传给 LLM，模型靠它理解参数含义；每个字段的 description 必须标注适用的 agent（如 "reviser only: revision mode"）
枚举用 Union+Literal — 有限合法值用 Type.Union([Type.Literal("a"), Type.Literal("b")]) 而非 Type.String()，模型能在 JSON Schema 里看到 const 约束，不会传错
开放文本用 String — 书名、题材等无法穷举的值用 Type.String({ description: "..." })
Optional 包裹可选字段 — Type.Optional(...) 标记非必填参数
不硬编码 pipeline 参数 — sub_agent 的参数必须与 pipeline runner 方法签名对齐，不能在 execute 里写死值（如 genre: "general"）
返回值要可操作 — agent 收到的返回文本必须包含足够信息让它决定下一步（如 auditor 返回 issue 列表而非只返回数量）
错误抛异常 — execute 里不要 catch-and-encode 错误到返回值，throw 由 agent loop 统一处理

关键路径

Agent 工具: core/src/agent/agent-tools.ts → SubAgentParams schema → createSubAgentTool → 调用 PipelineRunner 方法
建书流程: core/interaction/project-tools.ts → CREATE_BOOK_TOOL + chatWithTools → Studio ChatPage → BookFormCard
Studio 入口: studio/src/App.tsx → route 驱动页面切换
状态管理: Zustand store，LobeHub slice 约定
- studio/src/store/chat/ — 对话消息、创建流程、侧边栏状态
- studio/src/store/service/ — 服务商连接状态、模型列表缓存、model picker 三态（loading/no-models/ready）
- 原则: Zustand selector 只返回 store 中已有的原始值。如果需要 .filter() / .map() 等产生新数组的派生，用组件内 useMemo 而不是 store selector — 否则会造成无限渲染循环
SSE 事件: studio/src/hooks/use-sse.ts（共享 buffer）+ 组件内直连 EventSource（流式渲染）
服务商 preset: core/src/llm/service-presets.ts → baseUrl/api/knownModels/modelsBaseUrl；Anthropic 兼容端点用于 MiniMax 和百炼

3.8 KiB Raw Permalink Blame History Unescape Escape