# @customize-agent/server 中文文档

规范地址：https://npmcn.com/package/%40customize-agent/server/

版本：4\.61\.29
npm 元数据更新时间：2026-10-29T12:23:55.741Z
中文译文更新时间：2026-11-11T05:22:15.593Z
软件包许可：未声明

本文由上游 README 翻译，可能存在偏差，请结合原文核对 API、命令与配置。版权与许可归原作者所有。

原始 npm 页面：https://www.npmjs.com/package/%40customize-agent/server
原文对照：https://npmcn.com/package/%40customize-agent/server/?lang=original

## 关键信息（来自 npm 元数据）

- 包体积（解压后）：30.5 MB，276 个文件
- TypeScript 类型：未声明
- Node.js 要求：\>=22\.19\.0
- 运行依赖：20 个
- 首次发布：2026-07-04T09:51:51.596Z
- 最新版本发布：2026-10-29T12:23:55.136Z
- 近 30 天下载量：11900（2026-10-11 至 2026-11-09，npm 官方下载统计）
- 已发布版本数：481（近 12 个月 481 个）

## 中文简介

自定义代理 Web QQ

## 安装

```sh
npm install @customize-agent/server
```

也可以使用：`pnpm add @customize-agent/server`、`yarn add @customize-agent/server`、`bun add @customize-agent/server`

## README

# Customize Agent Web 控制台（apps/server）

前端 + API 同体的应用本体（Next.js Pages Router，默认端口 **17321**）。 界面语言：画布（唯一生成视图）+ 管理页；不含 CLI（已拆除）。

## 页面

| 路由 | 作用 |
| --- | --- |
| `/` → `/overview` | 数据总览：系统统计、provider、提示词、生成记录、知识库分类、**数据体检与清理** |
| `/canvas` | 新建生成：画布 + 底部输入条（提示词选择 / 项目选择 / 一句自然语言指令） |
| `/canvas/[id]` | **主画布**：节点树、状态、技能命中、交接气泡、修复浮层、跟随最近；唯一生成视图落点 |
| `/documents` | 重定向到 `/canvas`（记录列表已并入画布悬浮小球） |
| `/knowledge`、`/knowledge/manage`、`/knowledge/file-detail` | 知识库：上传、索引状态、检索、标签/忽略规则相关 API |
| `/prompt` | 提示词库（内置示例 + 项目 `CUSTOMIZE.md`） |
| `/skills` | 技能编辑器（闭集词表由服务端下发；内置技能只读，编辑即复制） |
| `/models`、`/settings`、`/system/logs`、`/guide` | 模型配置、设置、日志、指引 |

## 关键 API

-   `POST /api/documents/generate` —— 启动生成。请求体三字段：`promptIds` / `requirement` / `projectRoot` （可选 `materialRoot`、`title`）。**章结构由提示词大纲派生**（`deriveDocumentSpec`），没有模板概念。
-   `GET /api/documents/canvas/[id]` —— 画布聚合视图（一次读盘喂满画布，可降级）。
-   `GET /api/documents/generated/[id]`（`lite=1/2` 投影裁剪）· `.../nodes` · `.../events`（SSE）· `.../pause` · `.../resume-generate` · `.../instruction`（输入框=交互式入口）· `.../repair` → `[rid]/confirm` → `[rid]/rollback`（人工确认修复事务）· `.../figure/[name]`（确定性 SVG）。
-   `POST /api/documents/export` —— 导出 md/html/docx/pdf；门禁未过需 `allowNonDeliverable`（加「非交付物」后缀）。
-   `GET/POST /api/kb/*` —— 文件、树、搜索、上传、索引、标签、忽略规则、重复、评测。
-   `GET/PUT /api/config/{models,providers,embedding,web-access}` · `/api/skills/*` · `/api/prompt` · `/api/system/{stats,logs,data-health}`。

## 服务分层（第 23.5 节目录重划后）

旧的 `services/document-workflow/`（"文档工作流"）已按**实际职责**拆开，不再存在该目录：

-   `services/construction-domain/` —— 施工域业务对象与事务（工作库、工作包、原量分配、生产与共享定义、工期精算、准入闸）。
-   `services/facts-evidence/` —— 证据与事实（来源版本政策、事实模型、招标义务、工程量清单、CAD 事实）。
-   `services/document-assets/` —— 文档资产：`chapter-plan/`（章节与规划）、`authoring/`（正文与图件写作）、`contract-delivery/`（合同、终检与交付）。
-   `services/generation-runtime/` —— 生成运行时与模型调用（LLM 客户端、调用账、诊断、检查点、模型配置）。
-   `services/shared/` · `services/contracts/` —— 跨组共享工具与跨层类型契约。
-   `services/archive/` —— **只读归档**：旧执行链的证据回放（不授予任何新的工程资格）。
-   `services/document-core/` —— 生成记录的持久化与任务调度（并发默认 2、按项目互斥、暂停/恢复、中断归档）。
-   `services/agent/` —— 节点运行时（`emitNode` 唯一写入口、`nodeLog` append-only、工具注册表）与持续职责运行时。
-   `services/skills/` —— 技能契约与内置技能；`services/knowledge/` —— 知识库单例与索引子进程。

**当前生成状态**：新链路的正式装配尚未接通，生成唯一的入口是 HTTP 路由 `POST /api/documents/generate`——未就绪时在入口**显性拒收**（503，`CONSTRUCTION_RUNTIME_NOT_READY`）。 独立的"生成入口／收口入口"墓碑函数与旧执行器均已删除，不保留任何可被再次 `import` 的回退通道。

## 本地数据

见根 `README.md`。记录本体在 `~/.customize-agent/projects/<id>/generatedDocuments/`； **节点日志（`*.nodes.jsonl`）是唯一真相**，`executionStages` 是它的派生投影。

## 开发

```bash
pnpm --filter @customize-agent/server dev      # :17321（先清 .next）
pnpm --filter @customize-agent/server build    # 构建 + verify-next-static
pnpm typecheck && pnpm lint
npx vitest run                                 # 全仓测试（根目录跑）
```

改画布/布局类代码后**必须**跑真浏览器像素用例（jsdom 不做布局）： `npx vitest run --config vitest.manual.config.ts apps/server/test/pages/canvas/canvasLayoutPixels.manual.ts`

## 常见问题

### @customize-agent/server 是什么？

自定义代理 Web QQ

### 如何安装 @customize-agent/server？

在项目目录运行 npm install @customize-agent/server，或使用 pnpm add / yarn add / bun add。它还提供命令行工具 customize-web、customize-dashboard，可以用 npx customize-web 直接运行。

### @customize-agent/server 支持 TypeScript 吗？

该包的 package\.json 没有声明类型入口。需要类型提示时，可以在 npm 上查找社区维护的 @types/customize-agent\_\_server 是否存在。

### @customize-agent/server 需要什么版本的 Node\.js？

package\.json 的 engines 字段要求 Node\.js \>=22\.19\.0。版本不符时 npm 默认只给出警告，开启 engine-strict 后会拒绝安装。

### @customize-agent/server 可以商用吗？

@customize-agent/server 使用 未声明 许可。package\.json 没有声明许可证。没有许可证的代码默认保留全部权利，商用前请联系作者或查看仓库中的 LICENSE 文件。以上为概括，不构成法律意见，请以许可原文为准。

### @customize-agent/server 的下载量有多少？

根据 npm 官方下载统计，@customize-agent/server 在 2026/10/11 – 2026/11/09 这 30 天内被下载 11,900 次，日均约 397 次。下载量会把 CI 构建、镜像同步和作为其他包依赖的安装一并计入，适合横向比较热度，不能直接等同于使用人数。

### @customize-agent/server 还在维护吗？

最新版本 4\.61\.29 发布于 2026/10/29（12 天前）；至今共发布 481 个版本，其中过去 12 个月发布了 481 个；首次发布于 2026/07/04。发布频率只是参考信号：功能稳定的工具可能很少需要更新，建议结合源码仓库的 issue 和提交记录判断。