天枢 (Tiānshū) — Terminal Coding Agent

Node.js 24（engines 钉 24.1.0）+ TypeScript strict + 纯 ANSI 终端 UI（src/tui/engine/，零 React/Ink 渲染）+ DeepSeek V4 API。桌面端 desktop/ 是独立 React 应用。

Commands

npx tsc --noEmit                                  # typecheck
npm exec -- tsx --test src/**/__tests__/*.test.ts # all tests (node:test + assert/strict)
npm run build                                      # tsup bundle
npm run dev                                        # tsup --watch
node dist/main.js                                  # launch

Approval Mode

rivet config set-approval dangerously-skip-permissions  # trusted workspaces: skip all approval prompts
rivet --dangerously-skip-permissions                    # one-session override
rivet config set-approval auto-safe                     # restore recommended smart-safe mode

dangerously-skip-permissions only skips interactive approval prompts; tool validation, path safety, reliability hard blocks, evidence tracking, checkpoints, and delivery gates still run. Full note: docs/dangerously-skip-permissions.md.

Typecheck + tests is the minimum verification after any code change. 测试范围按改动类型选择：普通改动跑同名前缀 glob (X*.test.ts，覆盖姊妹文件如 X-cache-stability.test.ts)；缓存/不变量/前缀结构改动跑模块目录全量 (__tests__/*.test.ts)。声称"N/N 绿"前确认 N 对得上被影响的测试文件总数——N 太小就是没测全的信号。详见 .rivet/knowledge/sibling-test-coverage.md。

Code Conventions

TypeScript strict mode, noUncheckedIndexedAccess: true
No classes for data — use interface + plain objects
Async/await with try-catch, never bare Promise chains
Tools return ToolResult { content, isError?, rawPath?, uiContent? }
New tools must register in src/tools/default-registry.ts and have tests
Test framework: node:test + node:assert/strict
Test files mirror source: src/agent/foo.ts → src/agent/__tests__/foo.test.ts

TDD Feasibility Probe（可行性探针）

写复杂测试前（树遍历、mock 链、render harness），先用 30 秒探针验证核心机制可行：

写 3 行代码单独验证你要依赖的那个底层能力
探针失败 → 立刻换更简单的方法
探针通过 → 再写完整测试

已知不可行的路径和替代方案 → 见 .rivet/knowledge/testing.md

Complex Spec Workflow（复杂规格工作流）

复杂 spec / shadow / telemetry / 跨模块集成任务不能只按 checklist 打勾；执行姿态必须升级为 dataflow verifier：

事实流图：spec 字段/约束 → 上游来源 → 中间结构 → 消费者/写入目标 → 测试断言
条件矩阵：组合条件（如 source × severity × apply）逐格判定，不把嵌套约束平铺成孤立 if
反证测试表：明确 checklist-only、happy-path、missing call contract、type-without-consumer、truthy/falsy sentinel 哪条测试会红

没有能打红错误实现的测试，不得声称 spec 已验证。

Semantic Disambiguation（语义消歧）

以下中文词汇在项目中有双重含义，遇到时需先确认用户意图，不确定时使用 ask_user_question：

词汇	含义 A（运行时/数据）	含义 B（代码/管理）
会话	会话对话记录 `<cwd>/.rivet/sessions/<id>.jsonl` + 同级 `.meta.json`（详见 AGENTS.md Runtime Data Layout）	会话管理代码 → `src/agent/session*.ts`、`SessionRegistry`
任务	当前正在执行的任务/todo	任务管理代码 → `TaskState`、`todo-store.ts`
缓存	运行时缓存命中率/状态	缓存管理代码 → `src/cache/`（advisor、cache-audit）、`scripts/verify-cache-hit-rate.ts`
星域	当前会话的星域状态（Sensorium）	星域系统代码 → `star-event.ts`、`star-domain.ts`
工具	工具调用历史/结果	工具实现代码 → `src/tools/*.ts`

消歧原则：用户说"看一下X"、"查一下X"且无代码路径 → 先假设含义A（数据）。出现 src/、.ts、函数名 → 含义B（代码）。

FilesExpand file tree

.rivet.md

Latest commit

History