q-code: Instructions file for Codex

q-code 项目协作说明

项目概览

q-code 是一个基于 Vercel AI SDK 的 TypeScript 命令行 Agent 框架。核心能力包括：

• Agent / 任务：Agent Loop、Plan Mode（自然语言审批、智能进入与 Shift+Tab 切换）、Task V2、TodoWrite、上下文压缩、会话持久化与 TUI /sessions 管理、文件历史快照与 /rewind 按轮次回滚内置写工具改动、TUI /agents SubAgent Monitor（同步与后台 SubAgent，completed 默认隐藏并可清理，忙碌等待期间可用 Ctrl+A 查看）、只读同步 SubAgent 动态并行调度、SubAgent 长 final output artifact/preview 回传、TUI 输入历史跨进程持久化、@file 文件引用注入与候选索引缓存/监听刷新、@image:<path> / TUI 图片附件多模态输入、文件派项目记忆（headers 精选、预算化正文注入、年龄提示）、Skills、SubAgent、Agent Teams、Worktree 隔离。
• 工具执行：文件/搜索工具、可配置超时与 spill 的 Shell 工具（Windows 优先 PowerShell7，缺失时回退 Windows PowerShell 5.1）、后台 Shell job（f_status / f_tail / f_kill / f_list）。
• 集成扩展：MCP server、ACP v1 stdio Agent 接入、Hooks（生命周期事件、pre/post tool-use 决策、prompt/context 注入、退出码协议）、Slash 命令注册表、Output Styles、Markdown User Commands、企业 AI 基建同步（Infra）、GitLab Wiki 知识库。
• 可观测性：NDJSON 审计日志（默认开启）、本地只读 Web Dashboard、模型等待心跳、ttftMs/elapsedMs/TPS step 诊断、可选 Langfuse/OpenTelemetry trace 导出、崩溃保护（crash guard，默认开启）与 crash report、Usage / Cache / 成本统计、上下文占用预警、启动时版本更新说明（对比 ~/.q-code/last-version.json 与包内 changelog.json）。
• 评测：q-code eval 本地优先 Agent 质量平台，覆盖固定任务集、mock/cli/真实模型 runner、LLM judge（opt-in）、工具轨迹、预算/成本、进度、文件副作用、策略安全、JSONL trace、Markdown/JUnit 报告、baseline 对比、趋势看板、定期回归与可选 Langfuse evaluator trace / dataset / scores 导出。
• TUI：基于 Ink 的交互式 TUI（默认）、流式 Markdown 稳定前缀渲染、Markdown 快路径与 LRU parse cache、--classic 经典 readline、可经管道/CI 自动降级；主 Agent 默认人格为「小黄鸭」，可用 /ya 主动切换到主题鸭「降压鸭」「屁老鸭」。
• CLI 子命令：q-code help|version|update|audit|init|eval|dashboard|exec|acp（启动前 short-circuit）；exec 提供 Codex CLI 兼容的无头 JSONL、session resume 和常用参数；acp 以 ACP v1 stdio Agent 身份提供 session/prompt；其余参数走主交互循环。

环境与工具

• 运行时：Node.js 22+。
• 包管理器：pnpm。不要混用 npm/yarn 生成新的 lockfile。
• 源码直接通过 tsx 运行，项目为 ESM：package.json 中 "type": "module"。
• TypeScript 严格模式开启，模块解析为 bundler，目标为 ES2022。
• 本仓库存在 .env，其中可能包含本地敏感配置；不要在回复、日志或提交中暴露密钥明文。

常用命令

pnpm install
pnpm start                  # tsx src/index.ts
pnpm continue               # tsx src/index.ts --continue

pnpm docs:dev               # VitePress 文档站本地预览
pnpm docs:build             # 构建 docs/.vitepress/dist
pnpm docs:preview           # 预览文档站构建产物

pnpm typecheck              # tsc --noEmit
pnpm test                   # vitest run（unit + integration）
pnpm test:unit              # vitest run tests/unit
pnpm test:integration       # vitest run tests/integration
pnpm test:acp               # ACP 参数、内容转换和 stdio 握手测试
pnpm test:watch             # vitest watch
pnpm test:coverage          # vitest run --coverage

pnpm test:legacy            # 串行：test-mcp + test-skills + test-agents + test-async-agents + test-teams
pnpm test:mcp
pnpm test:skills
pnpm test:agents            # test-agents + test-async-agents
pnpm test:teams
pnpm test:infra-candidate

pnpm eval:smoke             # 运行 deterministic smoke eval，不导出 Langfuse
pnpm eval:cli               # 运行 cli-subprocess fixture eval，不导出 Langfuse
pnpm eval:ci                # 运行 smoke + cli eval，并输出 JUnit 报告
pnpm eval:smoke:langfuse    # 运行 smoke eval 并按配置导出到 Langfuse
pnpm eval:nightly           # 运行定期 deterministic 回归并生成趋势看板
pnpm eval:trend             # 从历史 eval runs 生成本地趋势看板
pnpm eval:compare           # 对比两个 eval run
pnpm prompt:cache:verify    # 本地验证稳定 system prompt hash 与 90%+ 前缀目标
pnpm prompt:quality:verify  # 本地审计 Agent prompt 12 维质量基线

pnpm test:all               # pnpm test && pnpm test:legacy
pnpm precommit              # typecheck + test:unit
pnpm build                  # 调 scripts/build.mjs：自动生成 changelog 并产出 dist/
pnpm changelog              # 手动从 git tag / conventional commit 生成 CHANGELOG（调试用）