codeapp_agent

v1.0.8

Published

3 months ago

CodeApp: AI-powered terminal & service assistant dedicated to the Next.js + next-admin stack.

0High
0Medium
0Low

skingko

CodeApp

CodeApp 是专为 Next.js 14 + next-admin 技术栈打造的 AI 辅助开发环境。它同时提供交互式终端客户端与常驻 Server 模式，可在受控工作空间内完成脚手架搭建、开发调试、质量检查与自动化发布。

环境准备

操作系统：macOS、Linux 或 WSL2。Server 模式已在 macOS/Linux 验证。
Node.js：>= 20.18.1（package.json 中 engines 已限制）。
pnpm：推荐 v8 及以上；若系统安装 Bun，可用于 pnpm dev 的即时运行。
Git：推荐用于项目版本管理。
可选项：Kafka 集群、Anthropic/OpenAI 等 LLM 凭证、Git SSH 密钥。

目录结构

kode/
├─ src/                  # CLI、服务、工具的 TypeScript 源码
├─ dist/                 # `pnpm run build` 生成的 ESM 编译结果
├─ cli.js                # 构建后生成的跨平台启动包装脚本
├─ docs/                 # Service API、开发者指南、设计文档
├─ .codeapp/agents/      # 内置子代理提示词
├─ scripts/              # 构建、发布脚本
├─ yoga.wasm             # 捆绑的 Yoga 布局引擎
└─ README*               # 中英文使用文档

构建流程会为每个源文件生成对应的 .js，同时写入 dist/package.json（type: module）。顶层 cli.js 优先加载编译后的入口，如未构建则回退到 Bun/tsx 运行。

安装与构建

pnpm install              # 安装依赖
pnpm run build            # 编译到 dist/ 并生成 cli.js
pnpm exec tsc --noEmit    # 仅类型检查（自动化流程也会执行）

构建产物：

dist/：与 src/ 等结构的 ESM 输出
dist/index.js：延迟加载 CLI 的 ESM 入口
dist/entrypoints/cli.js：编译后的 CLI 主体
cli.js：Node→Bun→tsx 的多重启动包装器

CI 或发布前建议执行 pnpm run build && pnpm exec tsc --noEmit，确保代码、提示词和类型均通过。

命令行使用方式

交互式 REPL

pnpm dev                # 调用 bun/tsx 直接运行 TS 源码
codeapp                 # 全局安装后可直接调用
./cli.js                # 构建后本地启动
node dist/index.js      # 直接运行编译产物

根命令支持以下选项：

| 选项 | 说明 | | ---- | ---- | | -c, --cwd <path> | 指定工作目录，会触发工作区解析与权限授权。 | | -d, --debug | 打开调试日志。 | | --debug-verbose | 输出更详细的调试信息。 | | --verbose | 强制启用冗长输出（覆盖配置文件）。 | | -e, --enable-architect | 临时启用 Architect 工具。 | | -p, --print | 打印模式。需通过 stdin 或参数提供 prompt，仅输出一次结果后退出。 | | --safe | 严格模式，限制执行未授权命令。 | | <prompt> | 可选位置参数；若省略且 stdin 为 TTY，则进入 REPL。 |

REPL 中可继续使用斜杠命令（/help、/task、/todo 等）。完整列表可执行 codeapp --help 查看。

非交互输出模式

echo "概述 README" | ./cli.js --print --cwd /workspace
codeapp "生成数据库迁移" --print --safe

使用 --print 时必须通过参数或 stdin 提供输入，否则命令会返回非零状态。

全局安装

pnpm install --global .            # 从本地仓库全局安装
npm install -g codeapp_agent      # 从 npm Registry 安装
codeapp --help                     # 主命令
ca --help                          # 简写别名

全局安装会注册 codeapp 与 ca 两个可执行文件，均指向 cli.js。

Server 模式

新手推荐阅读：docs/use_start.md（完整中文入门与参数说明）

启动示例

CODEAPP_WORKSPACE_DIR=/workspaces/demo \
CODEAPP_API_PORT=7070 \
CODEAPP_SERVER_TOKEN="super-secret-token" \
./cli.js server start --host 0.0.0.0

工作目录优先级（高 → 低）：

CLI --cwd
CODEAPP_WORKSPACE_DIR
CODEAPP_PROJECT_DIR
CODEAPP_TEMPLATE_TARGET_DIR
CODEAPP_TEMPLATE_SOURCE_DIR
当前目录下的 starter_temp
启动进程的当前目录

服务启动后会把最终目录写回 CODEAPP_WORKSPACE_DIR，并拒绝任何试图逃逸此目录的请求（返回 400 INVALID_WORKSPACE）。所有接口需携带 Authorization: Bearer <token> 或 X-CodeApp-Token 头部。

API 接口

POST /api/v1/prompt：提交 prompt（支持 --safe、--verbose 等标志）

POST /api/v1/prompt HTTP/1.1
Authorization: Bearer super-secret-token
Content-Type: application/json

{
  "user_id": "team-123",
  "task_id": "uuid-1",
  "prompt": "生成 Project CRUD",
  "cwd": "./apps/admin",
  "args": ["--safe"]
}

响应体仅返回 user_id、task_id，用于后续轮询。

GET /api/v1/tasks/:userId/:taskId：查询任务状态、日志与结果（支持 ?tail=50、?head=10）

详细协议可参考 docs/reference/api.md。

任务生命周期

校验请求体：user_id、task_id 必填，prompt 与 args 至少二选一。
解析并锁定工作目录，创建任务会话。
executePromptTask 会准备运行时环境，尊重 --safe / --verbose 等标志并执行 prompt。
日志会同步到 taskManager（轮询接口）与 /tasks/:userId/:taskId/stream（SSE）。
任务状态由 taskManager 持久化，可通过 GET 接口轮询。

预置资源与子代理

首次启动 CLI 或 Server 时，会将打包资源释放到 ~/.codeapp（可通过 CODEAPP_HOME_DIR 覆盖）。已有文件不会被覆盖，新增文件会自动补齐。
~/.codeapp/subagents/doc_reader.md：面向 ~/codeapp_docs 的文档阅读子代理，用于汇总框架说明与架构笔记。
~/.codeapp/subagents/style_reference.md：分析设计参考图的子代理，每次处理一张图片，并输出对应的 shadcn/ui 与 Tailwind 实现提示。
~/.codeapp/core_prompt.ts：追加到系统提示词尾部，可结合项目需求自定义（或使用 CODEAPP_CORE_PROMPT_PATH 指向其他文件）。
~/.codeapp/preconfig/*.example：示例配置，复制并去掉 .example 后缀即可在后续打包/解压中生效。
~/.codeapp/scripts/startup.sh：Server 模式启动时会在工作目录执行该脚本（永远覆盖释放到 <workspace>/.codeapp/startup.sh）。可自定义为 pnpm dev 等。

受控终端与日志工具

Server 启动后会在工作目录运行受控终端（执行 startup.sh）。
使用 TerminalLog 工具可随时读取终端输出（默认允许，建议 tail: 200 查看最近日志）。
~/.codeapp.json：首次安装会合并预置的 MCP 服务器配置，保留原有条目并追加缺失项。

环境变量详解

所有变量均通过 process.env 读取，export 的值优先级最高；.env 仅在变量不存在时补齐默认值。以下按功能分组说明。

工作目录解析

| 变量 | 作用 | 默认值 / 备注 | | ---- | ---- | ------------- | | CODEAPP_WORKSPACE_DIR | 锁定 CLI/Server 的工作根目录。 | 自动化流程会写回此变量，优先级最高。 | | CODEAPP_PROJECT_DIR | 备用工作目录提示。 | 解析后会写回 CODEAPP_WORKSPACE_DIR。 | | CODEAPP_TEMPLATE_TARGET_DIR | 指定模板输出目录。 | 同样会写回 CODEAPP_WORKSPACE_DIR。 | | CODEAPP_TEMPLATE_SOURCE_DIR | 模板源目录，create 的主要输入。 | 若其他变量缺失，也会作为工作目录。 | | CODEAPP_STARTER_SOURCE_DIR | 模板源的备用路径。 | 在主路径缺失时尝试。 | | starter_temp 目录 | worktree 中的默认模板。 | 当以上变量均未设置时使用。 |

鉴权与预置资产

| 变量 | 作用 | 备注 | | ---- | ---- | ---- | | CODEAPP_SERVER_TOKEN | Server 模式的全局鉴权 Token。 | 通过 Authorization: Bearer 或 X-CodeApp-Token 传递。 | | CODEAPP_CORE_PROMPT_PATH | 自定义系统提示词尾部追加的文件。 | 默认使用 ~/.codeapp/core_prompt.ts。 | | CODEAPP_HOME_DIR | 预置资源解压目录。 | 默认 ~/.codeapp。 |

Kafka 日志镜像

| 变量 | 作用 | 默认值 | | ---- | ---- | ------ | | CODEAPP_KAFKA_ENABLED / KAFKA_ENABLED | 启用 Kafka 输出。 | false | | CODEAPP_KAFKA_BROKERS / KAFKA_BROKERS | Broker 列表（逗号分隔）。 | — | | CODEAPP_KAFKA_TOPIC / KAFKA_TOPIC | 推送的 Topic。 | codeapp.logs | | CODEAPP_KAFKA_CLIENT_ID | 客户端标识。 | codeapp-agent | | CODEAPP_KAFKA_SSL | 设为 true 开启 TLS。 | false | | CODEAPP_KAFKA_SASL_USER / CODEAPP_KAFKA_SASL_PASS | SASL 用户名/密码。 | — |

LLM 服务提供商

只建议同时启用一种供应商。

Anthropic | 变量 | 说明 | | ---- | ---- | | ANTHROPIC_API_KEY | 标准 API Key（默认使用）。 | | ANTHROPIC_AUTH_TOKEN | 兼容旧版 Token。 | | ANTHROPIC_BASE_URL | 自定义代理地址。 | | ANTHROPIC_MODEL | 默认模型覆盖。 | | ANTHROPIC_BEDROCK_REGION / ANTHROPIC_BEDROCK_MODEL / AWS_ACCESS_KEY_ID / AWS_SECRET_ACCESS_KEY | 走 Bedrock 所需参数。 | | ANTHROPIC_VERTEX_PROJECT_ID / ANTHROPIC_VERTEX_LOCATION / GOOGLE_APPLICATION_CREDENTIALS | 走 Vertex AI 所需参数。 |

OpenAI 或兼容接口 | 变量 | 说明 | | ---- | ---- | | OPENAI_API_KEY | OpenAI/兼容接口的认证 Key。 | | OPENAI_BASE_URL | 自定义接口地址（如 Azure、私有代理）。 | | OPENAI_API_VERSION | Azure OpenAI 需指定的 API 版本。 | | OPENAI_MODEL | 默认模型覆盖。 |

如需调整不同任务的模型，请编辑 ~/.claude/config.json 或项目目录下的 .claude/config.json，修改 modelProfiles 与 modelPointers（详见 docs/develop/configuration.md）。

其他配置

| 变量 | 说明 | | ---- | ---- | | CODEAPP_CONFIG_DIR / CLAUDE_CONFIG_DIR | 更改全局配置目录（默认 ~/.codeapp）。 | | CODEAPP_TASK_LOG_LIMIT | Server 模式下任务日志的保留条数。 | | CODEAPP_BASH | 指定持久化 shell 工具使用的可执行文件。 | | LOG_LEVEL | 调整调试日志输出级别。 | | NODE_ENV | 推荐在部署时设为 production。 |

.env 与 export 的优先级

加载顺序如下：

CLI 参数（例如 codeapp server start --port 9090）。
启动进程时已存在的环境变量（shell export、systemd/docker 传入的变量）。
.env 文件内的键值（仅在前两层缺失时填充）。

因此建议：本地开发在 .env 中写默认值，部署环境通过 export 或进程管理器注入敏感信息。

打包与分发

复制构建产物：执行 pnpm run build 后，将 dist/ 与 cli.js 拷贝到任意安装了 Node 20+ 的主机，直接运行 ./cli.js。
生成压缩包：npm pack 或 pnpm pack 会输出 @codeapp/agent-<version>.tgz，其他环境使用 npm install -g ./包名.tgz 即可完成安装。
发布到 npm：更新 package.json 的版本号，确认测试通过后执行 npm publish --access public。安装后会生成 codeapp 与 ca 两个命令。

Docker/VM 部署场景：安装依赖 → 导出配置 → 通过 ./cli.js server start 在进程管理器（systemd、pm2、Docker ENTRYPOINT）下运行。

故障排查与诊断

pnpm run build：重新编译 CLI（留意require→ESM 相关警告）。
pnpm exec tsc --noEmit：检测类型声明遗漏（例如 src/types/sharp.d.ts）。
pnpm lint / pnpm lint:fix：修复/检查代码风格。
pnpm test：执行 Bun 测试套件。
日志默认位于 ~/.codeapp/logs，若启用 Kafka 则同步到指定 Topic。
codeapp doctor：运行环境诊断并尝试修复常见问题。
Server 模式出现权限错误时，确认请求 cwd 是否位于 CODEAPP_WORKSPACE_DIR 内。

贡献指南

Fork 并克隆仓库。
执行 pnpm install 安装依赖。
提交前运行 pnpm run build && pnpm exec tsc --noEmit && pnpm lint && pnpm test。
更新中英文 README 及相关文档，保证双语同步。
新增提示词或子代理需同步 .codeapp/agents 与 docs/ 目录。