cardbuddy 0.13.3 → 0.14.1

package/README.md

@@ -125,10 +125,14 @@ agent 侧配置（`cwd` 必须是卡片工程根，读写才落在 `src/cards/`
 
 `cardbuddy init` 生成的工程已带 `npm run mcp` 脚本。回归见 `tools/tests/cardbuddy-mcp.test.mjs`。
 
+> 第一次接 agent 的人建议先读 dsl-card 仓库的 `docs/CardBuddy MCP 新手教程.md`：角色拓扑、
+> Codex / Claude / Cursor 三种注册配置、实测的完整编辑闭环、四个最常见的坑与排查手册。
+> （该文件在仓库 `docs/` 下，不在本包 `files` 白名单内，故只给路径不给链接。）
+
 ### 工具对本地服务的依赖分档
 
 `--mcp` 自己不启服务。启动时自动注入 `CARD_ROOT=<工程根>` 与
-`CARD_API_BASE=http(s)://127.0.0.1:<端口>`（端口取 `FINMALL_CARD_PORT` / `DSL_DEV_PORT`，默认
+`CARD_API_BASE=http(s)://127.0.0.1:<端口>`（端口取 `CARDBUDDY_CARD_PORT` / `DSL_DEV_PORT`，默认
 8787；已有同名环境变量时不覆盖），工具据此决定走 HTTP 还是本地降级：
 
 | 档 | 工具 |
@@ -292,7 +296,7 @@ DSL_DEV_HTTPS=1 cardbuddy
 
 ```bash
 npm run dev
-# → Vite dev server 端口 5180（由 .env.cb 的 FINMALL_DEV_PORT 控制）
+# → Vite dev server 端口 5180（由 .env.cb 的 CARDBUDDY_DEV_PORT 控制）
 # 浏览器打开 http://localhost:5180
 ```
 
@@ -333,7 +337,7 @@ npm run dev:prod
 
 ### 前置条件
 
-- `.env.cb` 已存在（含 `FINMALL_BASE_URL` 远端基址、`FINMALL_DEV_PORT`）。缺它编辑器仍能起，只是远端资源代理会告警。
+- `.env.cb` 已存在（含 `FINMALL_BASE_URL` 远端基址、`CARDBUDDY_DEV_PORT`）。缺它编辑器仍能起，只是远端资源代理会告警。
 - 首次跑前先 `npm install`（仓库根）。
 
 ### 服务侧单独起（调试 8787 本身）

package/dist/cli.js

@@ -3,11 +3,11 @@
  * cardbuddy CLI 入口（npm 包名与可执行命令同为 cardbuddy；0.6.0 前叫 cardbuddy-dev）。
  *
  * 读取 cwd 下 .env / .env.cb / .env.cb.local（dotenv），启动本地开发服务（127.0.0.1）。
- * 配置项见 src/config.js（DSL_CARD_ROOT / FINMALL_CARD_PORT / DSL_DEV_PORT /
+ * 配置项见 src/config.js（DSL_CARD_ROOT / CARDBUDDY_CARD_PORT / DSL_DEV_PORT /
  * DSL_DEV_TOKEN / DSL_DEV_HTTPS / EDITOR_URL / DSL_EDITOR_SRC）。
  *
- * 端口约定：.env.cb 的 FINMALL_CARD_PORT 为「卡片开发服务端口」单一真值，
- * 主仓库由 tools/dev.mjs 把它注入为 DSL_DEV_PORT；此处直接用 FINMALL_CARD_PORT，
+ * 端口约定：.env.cb 的 CARDBUDDY_CARD_PORT 为「卡片开发服务端口」单一真值，
+ * 主仓库由 tools/dev.mjs 把它注入为 DSL_DEV_PORT；此处直接用 CARDBUDDY_CARD_PORT，
  * 使 demo（直接 npx cardbuddy 或 npm run dev，无启动器注入）也能经 .env.cb 生效。
  */
 import fs from 'node:fs'
@@ -92,7 +92,7 @@ if (args.includes('--help') || args.includes('-h')) {
 
 环境变量:
   DSL_CARD_ROOT   卡片仓库根目录（默认 cwd）
-  DSL_DEV_PORT    本地服务端口（默认 8787，兼容 FINMALL_CARD_PORT）
+  DSL_DEV_PORT    本地服务端口（默认 8787，兼容 CARDBUDDY_CARD_PORT）
   DSL_DEV_HTTPS=1 启用自签 HTTPS
   DSL_DEV_TOKEN   可选鉴权 token
   DSL_DEV_PREVIEW=1 等价于 --preview

package/dist/config.js

@@ -3,9 +3,9 @@
  *
  * 约定：
  *   - 项目根默认 process.cwd()，可用 DSL_CARD_ROOT 覆盖。
- *   - 监听端口默认 8787，由 FINMALL_CARD_PORT 控制（.env.cb 单一真值）；
+ *   - 监听端口默认 8787，由 CARDBUDDY_CARD_PORT 控制（.env.cb 单一真值）；
  *     兼容旧 DSL_DEV_PORT（主仓库 tools/dev.mjs / prod-preview.mjs 注入）。
- *     前端 resolveApiBase 的 DEV 默认端口同样读 FINMALL_CARD_PORT，保持三者一致。
+ *     前端 resolveApiBase 的 DEV 默认端口同样读 CARDBUDDY_CARD_PORT，保持三者一致。
  *   - 编辑器 URL 默认 http://127.0.0.1:5180（EDITOR_URL），供截图使用。
  *   - 仅绑定 127.0.0.1；token / https 为可选增强。
  */
@@ -17,7 +17,7 @@ const __dirname = path.dirname(fileURLToPath(import.meta.url))
 
 /**
  * 取「真实环境变量」的值：排除 cli.js 用 dotenv 从 .env / .env.cb / .env.cb.local 灌进来的那份。
- * 没有这层区分，工程里 .env.cb 写了 FINMALL_CARD_PORT=8787 时，命令行的
+ * 没有这层区分，工程里 .env.cb 写了 CARDBUDDY_CARD_PORT=8787 时，命令行的
  * `DSL_DEV_PORT=9000 cardbuddy` 会被文件值静默顶掉（实测踩过）——显式命令行覆盖必须赢。
  * @param {Record<string,string|undefined>} env
  * @param {string} key
@@ -34,12 +34,12 @@ export function loadConfig(env = process.env) {
   const root = env.DSL_CARD_ROOT
     ? path.resolve(env.DSL_CARD_ROOT)
     : process.cwd()
-  // 端口优先级：真实环境变量（DSL_DEV_PORT > FINMALL_CARD_PORT）> .env 文件值
-  // （FINMALL_CARD_PORT > DSL_DEV_PORT，文件层以 FINMALL_CARD_PORT 为单一真值）> 默认 8787。
+  // 端口优先级：真实环境变量（DSL_DEV_PORT > CARDBUDDY_CARD_PORT）> .env 文件值
+  // （CARDBUDDY_CARD_PORT > DSL_DEV_PORT，文件层以 CARDBUDDY_CARD_PORT 为单一真值）> 默认 8787。
   const port = Number(
     realEnvValue(env, 'DSL_DEV_PORT') ||
-      realEnvValue(env, 'FINMALL_CARD_PORT') ||
-      env.FINMALL_CARD_PORT ||
+      realEnvValue(env, 'CARDBUDDY_CARD_PORT') ||
+      env.CARDBUDDY_CARD_PORT ||
       env.DSL_DEV_PORT ||
       8787
   )

package/dist/init.js

@@ -33,7 +33,7 @@ const ENV_TEMPLATE = `# CardBuddy 本地开发服务配置（共享层，可入
 # 个人机密（AI_API_KEY / FinMall 凭据等）请写 .env.cb.local，它覆盖本文件且不入库。
 
 # cardbuddy 本地服务端口（单一真值；编辑器前端也读它）
-FINMALL_CARD_PORT=8787
+CARDBUDDY_CARD_PORT=8787
 
 # FinMall 远端站点基址（资源代理回源 / 同步 / 保存 / 切图上传用）
 FINMALL_BASE_URL=https://uat-pkg.finmall.com
@@ -42,7 +42,7 @@ FINMALL_WORKSPACE_ID=dev
 # 远端编辑器 Web 访问别名（站点下挂载路径）
 FINMALL_EDITOR_PATH=/ubomp-h5-sub
 # Chrome 远程调试端口（复用已登录的 FinMall 会话）
-FINMALL_CDP_PORT=9222
+CARDBUDDY_CDP_PORT=9222
 
 # ---- AI 开发助手（自带网关，OpenAI 兼容 /chat/completions）----
 # AI_BASE_URL=https://your-gateway/openai/v1
@@ -54,6 +54,17 @@ FINMALL_CDP_PORT=9222
 # AI_ALLOW_SHELL=1
 # 单次输出上限：留空=自动（被 400 拒绝时自动减半重试）
 # AI_MAX_TOKENS=
+# ---- 长程任务保活（建卡一轮几十分钟属正常，默认值已按此调好，一般不用改）----
+# 上游多少毫秒不回任何字节算「网关静默」；静默会自动重试本步而不是整轮报废
+# AI_STALL_TIMEOUT_MS=120000
+# 网关静默后的自动重试次数（0=回到「一次静默即报错」）
+# AI_STALL_RETRIES=3
+# 单轮「纯思考」预算：到点催促 + 关深度思考重试，催促 3 次仍无产出则停用该熔断（改由墙钟兜底）
+# AI_REASONING_TIMEOUT_MS=600000
+# 模型没给收尾标记（[任务完成] / [需用户确认]）就停手时的自动续跑次数上限（0=关闭，等你手打「继续」）
+# AI_AUTO_CONTINUE=12
+# 单轮墙钟上限：唯一能兜住「无限跑下去」的闸门，到点收尾汇报（上下文不丢）
+# AI_TURN_TIMEOUT_MS=3600000
 `
 
 /** .gitignore 应包含的条目（缺哪条补哪条，不重写既有内容） */
@@ -157,7 +168,7 @@ npm run dev          # 等价于 npx cardbuddy
 \`\`\`
 
 然后在线上编辑器 **设置 → 本地开发服务** 里打开开关、填 \`http://127.0.0.1:8787\`
-（须与 \`.env.cb\` 的 \`FINMALL_CARD_PORT\` 一致）。
+（须与 \`.env.cb\` 的 \`CARDBUDDY_CARD_PORT\` 一致）。
 
 ## 目录约定
 
@@ -220,7 +231,7 @@ npm run link:skills   # 交互式选择 Codex / Claude / WorkBuddy 等，建立
 | **必须**另起服务 **且**已登录 FinMall | \`card_sync\` \`card_save\` \`card_slice_upload\` |
 
 \`--mcp\` 会自动把 \`CARD_ROOT\` 指到本工程根、\`CARD_API_BASE\` 指到 \`.env.cb\` 的
-\`FINMALL_CARD_PORT\`（默认 8787）。**别直接跑包内 \`vendored/mcp/server.mjs\`**：那样
+\`CARDBUDDY_CARD_PORT\`（默认 8787）。**别直接跑包内 \`vendored/mcp/server.mjs\`**：那样
 \`CARD_ROOT\` 会落到 node_modules 里的快照目录（\`card_list\` 返回 0 张卡），端口也回退到
 5180（\`card_render_status\` 直接报 \`dev-server-required\`）。排查时可设
 \`CARDBUDDY_MCP_VERBOSE=1\` 让启动信息打到 stderr。

package/dist/portGuard.js

@@ -249,7 +249,7 @@ export async function ensurePortFree({
   const before = await probePort(port, host)
   if (before.free) return result
   if (before.code !== 'EADDRINUSE') {
-    throw new Error(`端口 ${port} 无法绑定（${before.code}）。请检查权限，或用 FINMALL_CARD_PORT 换一个端口。`)
+    throw new Error(`端口 ${port} 无法绑定（${before.code}）。请检查权限，或用 CARDBUDDY_CARD_PORT 换一个端口。`)
   }
 
   const owners = await findPortOwners(port)
@@ -281,7 +281,7 @@ export async function ensurePortFree({
     const list = result.skipped.map((o) => `PID ${o.pid}${o.command ? ` — ${o.command}` : ''}`).join('\n  ')
     throw new Error(
       `端口 ${port} 被非 cardbuddy 进程占用，未自动结束：\n  ${list}\n` +
-        `请手动处理（${manualHint(port)}），或用 FINMALL_CARD_PORT 换端口；确需强制接管设 DSL_DEV_PORT_TAKEOVER=force。`
+        `请手动处理（${manualHint(port)}），或用 CARDBUDDY_CARD_PORT 换端口；确需强制接管设 DSL_DEV_PORT_TAKEOVER=force。`
     )
   }