context-engineer

把碎片想法编译成结构化的 AI 上下文文档。

当前状态

开源 Alpha 原型。Hono API + PostgreSQL/Redis 本地依赖 + React/Vite Web 工作台 + 轻量 CLI 已跑通。当前聚焦单模板场景：Codex / Claude Code subagent 配置。

这还不是生产版，重点是把核心闭环跑起来：

1. 输入碎片想法或需求记录
2. 匹配 claude-code-subagent@1.0.0 模板
3. 生成结构化字段并记录 provenance
4. 运行字段级 diagnostics
5. 导出 Markdown / YAML / JSON 配置

Screenshots

五步工作台：输入碎片 → 模板匹配 → 字段填充 → 诊断检查 → 导出

发布状态

模块	状态
Web 工作台	可本地试用
API / Repository / PostgreSQL	可本地试用
Assistant 字段生成	默认 mock，可切到 BYOK LLM
EvalKernel 语义判断	默认 mock，可切到 BYOK LLM
Diagnostics	Static 已可用，LLM 层取决于 EvalKernel 模式
多模板	推迟到 V1.1
用户认证	暂无，不建议公网裸部署
CI/CD	待补
LICENSE	MIT

MVP PRD 见 docs/specs/2026-05-23-context-engineer-mvp-prd.md。

架构边界见 docs/specs/2026-05-23-context-engineer-architecture.md。

完整设计见 docs/specs/2026-05-22-context-engineer-design.md。

是什么

面向 Codex / Cursor / Claude Code agent 构建者的工具：

1. 用户描述要构建的 agent / 要写的文档目标
2. 工具匹配领域模板，反推应有字段
3. 用户在结构化界面里填字段，工具诊断缺失、跑偏和风险点
4. 导出可直接使用的配置文件

与 prompt 编辑工具的核心区别：上下文从自由文本变成结构化字段集合，并保留字段级来源追溯和诊断。

项目结构

context-engineer/
├── AGENTS.md           # 项目协作规范与不变式
├── README.md           # 本文件
├── docs/
│   ├── specs/          # PRD / design / architecture
│   ├── plans/          # 实施计划
│   └── adr/            # 架构决策记录（未来）
├── src/                # Hono API、DB、repositories、services、CLI
├── tests/              # Vitest 单元测试
├── web/                # React/Vite 前端
├── docker-compose.yml  # 本地 PostgreSQL + Redis
└── package.json        # pnpm scripts

本地运行

安装依赖：

corepack pnpm install

启动数据库依赖：

docker compose up -d

生成并执行本地 migration：

corepack pnpm db:generate
corepack pnpm db:migrate
corepack pnpm db:seed

启动 Web 工作台：

CONTEXT_ENGINEER_STORAGE=database corepack pnpm dev

打开：

http://localhost:3000/

Windows PowerShell 写法：

$env:CONTEXT_ENGINEER_STORAGE='database'
corepack pnpm dev

运行模式

CONTEXT_ENGINEER_STORAGE：

• memory：默认内存模式，适合快速 API 测试，重启后数据丢失
• database：PostgreSQL 持久化模式，适合完整本地试用

CONTEXT_ENGINEER_ASSISTANT：

• mock：默认 mock 生成器，不需要外部密钥，不消耗额度
• llm：使用 CONTEXT_ENGINEER_LLM_PROVIDER 选中的真实 LLM 生成字段和改写字段
• anthropic：旧配置别名，兼容早期版本；新配置请用 llm

CONTEXT_ENGINEER_EVAL_KERNEL：

• mock：默认 mock 语义判断，不需要外部密钥，不消耗额度
• llm：Triage 和 Diagnostics 共享 CONTEXT_ENGINEER_LLM_PROVIDER 选中的真实 LLM 语义判断入口
• anthropic：旧配置别名，兼容早期版本；新配置请用 llm

BYOK LLM 配置：

• CONTEXT_ENGINEER_LLM_PROVIDER：anthropic / openai / deepseek / kimi / zhipu / openai-compatible
• CONTEXT_ENGINEER_LLM_MODEL：覆盖默认模型
• CONTEXT_ENGINEER_LLM_BASE_URL：仅自定义 OpenAI-compatible 服务时需要
• CONTEXT_ENGINEER_LLM_TIMEOUT_MS：可选，默认 30000

Provider 默认值：

Provider	API Key env	Base URL	默认模型
anthropic	ANTHROPIC_API_KEY	https://api.anthropic.com	claude-sonnet-4-6
openai	OPENAI_API_KEY	https://api.openai.com/v1	gpt-4.1-mini
deepseek	DEEPSEEK_API_KEY	https://api.deepseek.com	deepseek-chat
kimi	KIMI_API_KEY	https://api.moonshot.ai/v1	moonshot-v1-8k
zhipu	ZHIPU_API_KEY	https://open.bigmodel.cn/api/paas/v4	glm-4-plus
openai-compatible	OPENAI_COMPATIBLE_API_KEY	通过 CONTEXT_ENGINEER_LLM_BASE_URL 配置	通过 CONTEXT_ENGINEER_LLM_MODEL 配置

真实 LLM 本地启动示例（DeepSeek）：

$env:CONTEXT_ENGINEER_STORAGE='database'
$env:CONTEXT_ENGINEER_ASSISTANT='llm'
$env:CONTEXT_ENGINEER_EVAL_KERNEL='llm'
$env:CONTEXT_ENGINEER_LLM_PROVIDER='deepseek'
$env:DEEPSEEK_API_KEY='your-key'
corepack pnpm dev

真实 LLM 本地启动示例（Kimi）：

$env:CONTEXT_ENGINEER_STORAGE='database'
$env:CONTEXT_ENGINEER_ASSISTANT='llm'
$env:CONTEXT_ENGINEER_EVAL_KERNEL='llm'
$env:CONTEXT_ENGINEER_LLM_PROVIDER='kimi'
$env:KIMI_API_KEY='your-key'
corepack pnpm dev

Web 顶部会显示当前 Assistant / EvalKernel 运行模式、provider、model 和 key 是否已配置，避免把 mock 输出误认为真实 AI。

CLI

导出已有文档：

corepack pnpm cli export <document_id> --format markdown
corepack pnpm cli export <document_id> --format json --out export.json
corepack pnpm cli export <document_id> --format yaml --out export.yaml

CLI 与服务端共用 storage 配置。数据库模式下先设置 CONTEXT_ENGINEER_STORAGE=database。

本地验证

corepack pnpm build
corepack pnpm lint
corepack pnpm test
corepack pnpm db:generate

corepack pnpm db:migrate 会改变数据库 schema，执行前按项目规范单独确认。

当前功能

• 项目创建、列表、归档
• 输入片段与 immutable artifact revisions
• 单模板 triage
• Assistant 字段填充与字段改写（mock / BYOK LLM）
• EvalKernel 语义判断（mock / BYOK LLM）
• 字段保存的 stale write 防御
• Provenance 创建、查看、校正、整段重关联
• Diagnostics 运行、忽略、应用建议、stale 标记
• 导出前 diagnostics gate
• Markdown / YAML / JSON 导出
• React 工作台与侧边栏功能页
• UI 运行模式提示、API 错误提示、ErrorBoundary

下一步

• 添加 GitHub Actions CI（build / lint / test）
• 添加前端 smoke 测试
• 认证与权限模型（公网部署前必需）
• README 截图 / demo GIF

推迟事项

以下不在当前 MVP 内：多模板真实匹配、Template Extractor、本地模型 fallback、CLI import/sync、Notion/Feishu/WeChat 导出、CompositeDocument、社区模板系统。