@lyra-ai/toolkit 0.2.1 → 0.2.3

package/QUICKSTART.md

@@ -1,6 +1,6 @@
 # @lyra-ai/toolkit Quickstart
 
-面向 AI agent 的零依赖禅道 CLI。
+面向 AI agent 的零依赖 CLI 工具集：**zentao**（禅道项目管理）和 **skillhub**（AI 技能包管理）。
 
 ## 安装
 
@@ -12,6 +12,7 @@ npm install -g @lyra-ai/toolkit
 
 ```bash
 zentao --help
+skillhub --help
 ```
 
 ## 初始化
@@ -89,3 +90,94 @@ zentao bug get 42
 | `ZENTAO_DEFAULT_PROJECT` | | 默认产品/项目 ID |
 | `ZENTAO_TOKEN_TTL` | | Token 有效期（秒，默认 3600） |
 | `ZENTAO_CACHE_STALE_MS` | | 缓存过期阈值（ms，默认 3600000） |
+
+---
+
+## skillhub 快速开始
+
+### 登录
+
+```bash
+skillhub login --token <your-token>
+```
+
+Token 从 SkillHub registry 获取，登录后凭证存储在 `~/.skillhub/credentials.json`。
+
+验证：
+
+```bash
+skillhub whoami
+```
+
+### 搜索与安装技能包
+
+```bash
+# 搜索技能包
+skillhub search code-review
+
+# 安装到用户级（所有项目可用）
+skillhub install code-review --scope user
+
+# 安装到项目级（仅当前项目）
+skillhub install code-review --scope project
+
+# 指定 agent profile
+skillhub install code-review --agent claude-code --agent cursor
+```
+
+### 管理技能包
+
+```bash
+# 查看已安装
+skillhub list --json
+
+# 诊断问题
+skillhub doctor
+
+# 更新技能包
+skillhub update --scope user
+
+# 移除
+skillhub remove code-review --scope user
+```
+
+### 发布技能包
+
+```bash
+skillhub publish ./my-skill
+```
+
+## skillhub 工作流
+
+```
+login（认证） → search（发现） → install（安装） → list/doctor（管理） → update（更新）
+```
+
+- **`login`** 存储 registry token
+- **`search`** 在 registry 搜索技能包
+- **`install`** 下载并安装到指定 scope
+- **`list`** 列出本地已安装技能包
+- **`doctor`** 诊断安装问题（缺失文件、冲突等）
+
+## skillhub Agent 集成要点
+
+- 默认输出 **JSON → stdout**，错误 → stderr
+- 退出码：`0` 成功 / `1` 通用错误 / `2` 参数错误 / `3` 认证失败 / `4` 网络错误
+- `--json` 强制 JSON 输出（部分命令默认即为 JSON）
+- `--agent` 可重复指定多个 profile
+
+```bash
+# Agent 典型用法
+skillhub login --token "$SKILLHUB_TOKEN"
+skillhub search code-review --json --limit 5
+skillhub install code-review --scope project --agent claude-code
+skillhub doctor --json
+```
+
+## skillhub 配置参考
+
+| 变量 | 必填 | 说明 |
+|---|---|---|
+| `SKILLHUB_TOKEN` | ✅ | Registry 认证 token |
+| `SKILLHUB_REGISTRY` | | Registry 地址（默认 `https://registry.skillhub.com`） |
+

package/README.md

@@ -13,7 +13,7 @@
 安装后，你的 AI 编码数据自动进入组织分析平台，生成专属的多维度效能看板。
 
 ```bash
-toolkit install claudecode --registry http://your-platform:38000
+toolkit install --agent claudecode --registry http://your-platform:38000
 ```
 
 - 会话结束后自动同步，无需手动操作
@@ -49,7 +49,7 @@ http://your-host:38000
 
 Elasticsearch 日志查询工具，支持链路追踪、时间窗口、关键词搜索、自动根因解析。首次使用运行向导配置。
 
-> 目前支持 [PlumeLog](https://github.com/vensecheng/plumelog) 索引格式（字段：`dateTime` / `dtTime` / `traceId` / `appName` / `className` / `content` / `logLevel`）。
+> 目前支持 [PlumeLog](https://gitee.com/plumeorg/plumelog) 索引格式（字段：`dateTime` / `dtTime` / `traceId` / `appName` / `className` / `content` / `logLevel`）。
 
 ```bash
 log-query init                                # 向导式配置（ES 地址 + 索引 + 应用名）
@@ -99,3 +99,42 @@ cd <本目录> && npm link
 ```json
 {"total":1,"count":1,"bugs":[{"id":"9","title":"t","severity":"1","priority":"2","status":"active","assignedTo":"a"}]}
 ```
+
+---
+
+## skillhub 命令速查
+
+AI 技能包管理器：搜索、安装、发布、管理 AI coding agent 技能包。
+
+- `skillhub version [--json]` → 输出版本号
+- `skillhub help [topic]` → 帮助信息（`topic` 为命令名）
+- `skillhub login --token <token> [--registry <url>]` → 登录 registry
+- `skillhub logout` → 清除本地凭证
+- `skillhub whoami` → 显示当前登录用户
+- `skillhub search [query] [--limit N] [--json]` → 搜索技能包
+- `skillhub install <slug> [--namespace <ns>] [--agent <profile>] [--scope user|project] [--max-file-size <size>] [--json]` → 安装技能包
+- `skillhub list [--scope user|project] [--json]` → 列出已安装技能包
+- `skillhub remove <slug> [--scope user|project] [--agent <profile>] [--json]` → 移除技能包
+- `skillhub doctor [--fix] [--json]` → 诊断技能包安装状态
+- `skillhub publish <path> [--json]` → 发布技能包到 registry
+- `skillhub update [--scope user|project] [--agent <profile>] [--json]` → 更新已安装技能包
+
+### Agent profiles（`--agent`）
+
+支持 15 种 AI coding agent 配置文件：`claude-code`、`codex`、`cursor`、`cody`、`continue`、`augment`、`copilot`、`tabnine`、`qoder`、`windsurf`、`aider`、`cline`、`roo`、`trae`、`generic`。可重复使用 `--agent` 指定多个。
+
+### 数据存储
+
+- 凭证：`~/.skillhub/credentials.json`
+- 配置：`~/.skillhub/config.json`
+- 用户级技能包：`~/.skillhub/skills/`
+- 项目级技能包：`<cwd>/.skillhub/skills/`
+
+默认输出 JSON（stdout），错误走 stderr。退出码：0 成功 / 1 通用错误 / 2 参数配置 / 3 认证失败 / 4 网络错误。
+
+## skillhub JSON 示例
+```json
+{"ok":true,"version":"0.1.0"}
+{"ok":true,"skills":[{"slug":"code-review","version":"1.2.0","scope":"user"}]}
+```
+

package/bin/skillhub.mjs

@@ -0,0 +1,4 @@
+#!/usr/bin/env node
+import { main } from '../src/skillhub.mjs';
+const code = await main();
+if (code != null) process.exit(code);

package/bin/toolkit.mjs

@@ -23,15 +23,18 @@ const cmd = args[0];
 const HELP = `toolkit — 研发工具集
 
 命令:
-  install claudecode --registry <url>   安装 Claude Code 插件
-  status                                 查看安装状态 + 待同步会话
-  flush                                  手动触发一次同步
-  config                                 配置管理(registry / include)
-  uninstall [--purge]                    卸载插件(--purge 同时删数据)
-  help                                   显示此帮助
+  install --agent <name> --registry <url>  安装插件(适配指定 AI Coding Agent)
+    --agent claudecode                      Claude Code(SessionEnd hook 插件)
+  status                                    查看安装状态 + 待同步会话
+  flush                                     手动触发一次同步
+  config                                    配置管理
+  uninstall [--purge]                       卸载插件(--purge 同时删数据)
+  help                                      显示此帮助
 
-其他:
-  zentao <subcommand>                    禅道 CLI(向后兼容)
+其他(独立命令):
+  zentao <subcommand>                       禅道 CLI
+  log-query <subcommand>                    日志查询 CLI
+  skillhub <subcommand>                     技能包管理 CLI
 `;
 
 async function main() {
@@ -41,24 +44,29 @@ async function main() {
     return;
   }
 
-  // toolkit install claudecode --registry <url>
+  // toolkit install --agent <name> --registry <url>
   if (cmd === 'install') {
-    const target = args[1]; // claudecode
-    if (target !== 'claudecode') {
-      console.error('目前只支持: toolkit install claudecode');
-      console.error('  用法: toolkit install claudecode --registry <url>');
+    const agentIdx = args.indexOf('--agent');
+    const agent = agentIdx >= 0 ? args[agentIdx + 1] : null;
+    if (!agent) {
+      console.error('ERROR: 缺少 --agent <name>');
+      console.error('  用法: toolkit install --agent claudecode --registry <url>');
+      console.error('  支持: claudecode');
+      process.exit(2);
+    }
+    if (agent !== 'claudecode') {
+      console.error(`ERROR: 暂不支持 agent "${agent}"。目前支持: claudecode`);
       process.exit(2);
     }
-    // 解析 --registry
     const regIdx = args.indexOf('--registry');
     let registry = regIdx >= 0 ? args[regIdx + 1] : null;
     if (!registry) {
       console.error('ERROR: 缺少 --registry <url>');
-      console.error('  用法: toolkit install claudecode --registry http://your-platform');
+      console.error('  用法: toolkit install --agent claudecode --registry <url>');
       process.exit(2);
     }
     const { install } = await import(pathToFileURL(path.join(srcDir, 'install.mjs')).href);
-    install(registry);
+    install(registry, { agent });
     return;
   }
 

package/package.json

@@ -1,12 +1,13 @@
 {
   "name": "@lyra-ai/toolkit",
-  "version": "0.2.1",
+  "version": "0.2.3",
   "description": "面向 AI agent 的零依赖开发工具集",
   "type": "module",
   "bin": {
     "toolkit": "./bin/toolkit.mjs",
     "zentao": "./bin/zentao.mjs",
-    "log-query": "./bin/log-query.mjs"
+    "log-query": "./bin/log-query.mjs",
+    "skillhub": "./bin/skillhub.mjs"
   },
   "engines": {
     "node": ">=18"
@@ -29,6 +30,7 @@
   "license": "MIT",
   "keywords": [
     "zentao",
+    "skillhub",
     "cli",
     "ai-agent",
     "zero-dependency"

package/src/config-cmd.mjs

@@ -1,14 +1,9 @@
 #!/usr/bin/env node
 /**
  * config-cmd.mjs — `toolkit config [get|set|unset|list]`
- * 管理 ~/.toolkit/config.json(registry / project-filter)。
+ * 管理 ~/.toolkit/config.json(registry / project-filter / es)。
  */
-import fs from 'node:fs';
-import path from 'node:path';
-import os from 'node:os';
-
-const TOOLKIT_DIR = path.join(os.homedir(), '.toolkit');
-const CONFIG_PATH = path.join(TOOLKIT_DIR, 'config.json');
+import { load, save, get, set, unset, CONFIG_PATH } from './shared/config.mjs';
 
 const HELP = `toolkit config — 配置管理
 
@@ -20,29 +15,28 @@ const HELP = `toolkit config — 配置管理
 
 可用配置项:
   registry        平台根地址(如 http://your-host:38000)
-  project-filter  项目过滤关键词,逗号分隔(如 my-project,backend);留空 = 全部上传
+  project-filter  项目过滤关键词,逗号分隔;留空 = 全部上传
+  es.url          ES 地址(log-query 用)
+  es.index        ES 索引模式
+  es.app          默认应用名
 `;
 
-function load() {
-  try { return JSON.parse(fs.readFileSync(CONFIG_PATH, 'utf-8')); }
-  catch { console.error('配置文件不存在。先运行: toolkit install claudecode --registry <url>'); process.exit(1); }
-}
-
-function save(config) {
-  fs.writeFileSync(CONFIG_PATH, JSON.stringify(config, null, 2));
-}
-
 export function configCmd(args) {
   const sub = args[0];
 
   if (!sub || sub === 'list' || sub === 'help' || sub === '--help') {
     const config = load();
+    if (!config.registry && !config.uid) {
+      console.error('配置文件不存在。先运行: toolkit install claudecode --registry <url>');
+      process.exit(1);
+    }
     const pf = config['project-filter'];
     console.log('Toolkit 配置 (' + CONFIG_PATH + ')');
     console.log('════════════════════════════════════════');
     console.log(`  registry:        ${config.registry || '(未设置)'}`);
     console.log(`  project-filter:  ${pf && pf.length ? pf.join(', ') : '(空 = 全部上传)'}`);
     console.log(`  uid:             ${config.uid?.slice(0, 12)}...`);
+    if (config.es) console.log(`  es.url:          ${config.es.url || '(未配置)'}`);
     console.log('════════════════════════════════════════');
     return;
   }
@@ -50,12 +44,16 @@ export function configCmd(args) {
   if (sub === 'get') {
     const key = args[1];
     if (!key) { console.error('用法: toolkit config get <key>'); process.exit(2); }
-    const config = load();
-    if (key === 'project-filter') {
-      const pf = config['project-filter'];
+    if (key.includes('.')) {
+      const [ns, ...rest] = key.split('.');
+      let cur = load()[ns];
+      for (const k of rest) cur = cur?.[k];
+      console.log(cur ?? '');
+    } else if (key === 'project-filter') {
+      const pf = get('project-filter');
       console.log(pf && pf.length ? pf.join(', ') : '');
     } else {
-      console.log(config[key] ?? '');
+      console.log(get(key) ?? '');
     }
     return;
   }
@@ -64,32 +62,27 @@ export function configCmd(args) {
     const key = args[1];
     const value = args.slice(2).join(' ');
     if (!key || !value) { console.error('用法: toolkit config set <key> <value>'); process.exit(2); }
-    const config = load();
-    if (key === 'project-filter') {
-      config['project-filter'] = value.split(',').map(s => s.trim()).filter(Boolean);
-    } else if (key === 'registry') {
-      config.registry = value.replace(/\/$/, '');
+    if (key.startsWith('es.')) {
+      const [, esKey] = key.split('.');
+      const config = load();
+      if (!config.es) config.es = {};
+      config.es[esKey] = esKey === 'url' ? value.replace(/\/$/, '') : value;
+      save(config);
+      console.log(`✅ ${key} = ${config.es[esKey]}`);
     } else {
-      config[key] = value;
+      set(key, value);
+      const display = key === 'project-filter'
+        ? (get('project-filter').join(', ') || '(空)')
+        : get(key);
+      console.log(`✅ ${key} = ${display}`);
     }
-    save(config);
-    const display = key === 'project-filter'
-      ? (config['project-filter'].join(', ') || '(空)')
-      : config[key];
-    console.log(`✅ ${key} = ${display}`);
     return;
   }
 
   if (sub === 'unset') {
     const key = args[1];
     if (!key) { console.error('用法: toolkit config unset <key>'); process.exit(2); }
-    const config = load();
-    if (key === 'project-filter') {
-      config['project-filter'] = [];
-    } else {
-      delete config[key];
-    }
-    save(config);
+    unset(key);
     console.log(`✅ ${key} 已清除`);
     return;
   }

package/src/flush.mjs

@@ -10,13 +10,9 @@ import os from 'node:os';
 import { deflateRawSync } from 'node:zlib';
 import { randomUUID } from 'node:crypto';
 import { fileURLToPath } from 'node:url';
+import { load as loadConfig, UPLOADED_PATH, LOG_DIR } from './shared/config.mjs';
 
-const __dirname = path.dirname(fileURLToPath(import.meta.url));
 const HOME = os.homedir();
-const TOOLKIT_DIR = path.join(HOME, '.toolkit');
-const CONFIG_PATH = path.join(TOOLKIT_DIR, 'config.json');
-const UPLOADED_PATH = path.join(TOOLKIT_DIR, 'uploaded.json');
-const LOG_DIR = path.join(TOOLKIT_DIR, 'logs');
 const CLAUDE_PROJECTS = path.join(HOME, '.claude', 'projects');
 
 // ── 日志 ──────────────────────────────────────────────
@@ -30,15 +26,8 @@ function log(...args) {
   if (process.env.TOOLKIT_VERBOSE) process.stderr.write(line);
 }
 
-// ── 读配置 ────────────────────────────────────────────
-function loadConfig() {
-  try {
-    return JSON.parse(fs.readFileSync(CONFIG_PATH, 'utf-8'));
-  } catch {
-    log('ERROR: config.json not found. Run `toolkit install` first.');
-    process.exit(1);
-  }
-}
+// ── 读配置(走 shared/config.mjs)─────────────────────
+// loadConfig 从 shared/config.mjs 导入
 
 function loadUploaded() {
   try {

package/src/install.mjs

@@ -8,11 +8,11 @@ import path from 'node:path';
 import os from 'node:os';
 import { randomUUID } from 'node:crypto';
 import { fileURLToPath } from 'node:url';
+import { load as loadConfig, save as saveConfig, TOOLKIT_DIR, UPLOADED_PATH, LOG_DIR } from './shared/config.mjs';
 
 const __dirname = path.dirname(fileURLToPath(import.meta.url));
 const HOME = os.homedir();
 const PLUGIN_DIR = path.join(HOME, '.claude', 'plugins', 'toolkit');
-const TOOLKIT_DIR = path.join(HOME, '.toolkit');
 const SETTINGS_PATH = path.join(HOME, '.claude', 'settings.json');
 const PLUGIN_KEY = 'toolkit@local';
 
@@ -36,7 +36,9 @@ const HOOKS_JSON = {
 };
 
 export function install(registry, opts = {}) {
+  const agent = opts.agent || 'claudecode';
   // 1. 检测 Claude Code
+  // (后续 --agent qoder 时,检测 ~/.qoder)
   const claudeDir = path.join(HOME, '.claude');
   if (!fs.existsSync(claudeDir)) {
     console.error('ERROR: ~/.claude not found. Is Claude Code installed?');
@@ -62,24 +64,18 @@ export function install(registry, opts = {}) {
   fs.copyFileSync(path.join(srcDir, 'hook.mjs'), path.join(PLUGIN_DIR, 'hook.mjs'));
   fs.copyFileSync(path.join(srcDir, 'flush.mjs'), path.join(PLUGIN_DIR, 'flush.mjs'));
 
-  // 5. 创建 ~/.toolkit/ 配置
-  fs.mkdirSync(TOOLKIT_DIR, { recursive: true });
-  fs.mkdirSync(path.join(TOOLKIT_DIR, 'logs'), { recursive: true });
-
-  // 读取已有 config(保留 uid)或新建
-  const configPath = path.join(TOOLKIT_DIR, 'config.json');
-  let config = {};
-  try { config = JSON.parse(fs.readFileSync(configPath, 'utf-8')); } catch {}
+  // 5. 创建 ~/.toolkit/ 配置(走 shared/config.mjs)
+  fs.mkdirSync(LOG_DIR, { recursive: true });
+  const config = loadConfig();
   if (!config.uid) config.uid = randomUUID();
   config.registry = registry.replace(/\/$/, '');
   config.contexts = { metrics: '/ai-metrics', skills: '/skillhub' };
   config.installed_at = new Date().toISOString();
-  fs.writeFileSync(configPath, JSON.stringify(config, null, 2));
+  saveConfig(config);
 
   // 6. uploaded.json 初始化(如果不存在)
-  const uploadedPath = path.join(TOOLKIT_DIR, 'uploaded.json');
-  if (!fs.existsSync(uploadedPath)) {
-    fs.writeFileSync(uploadedPath, JSON.stringify({ uploaded_sids: [], last_flush: null }, null, 2));
+  if (!fs.existsSync(UPLOADED_PATH)) {
+    fs.writeFileSync(UPLOADED_PATH, JSON.stringify({ uploaded_sids: [], last_flush: null }, null, 2));
   }
 
   // 7. 启用插件(settings.json)
@@ -92,7 +88,7 @@ export function install(registry, opts = {}) {
   // 8. 输出
   console.log('✅ 安装完成。\n');
   console.log(`   插件目录:  ${PLUGIN_DIR}`);
-  console.log(`   配置文件:  ${configPath}`);
+  console.log(`   配置文件:  ${path.join(TOOLKIT_DIR, 'config.json')}`);
   console.log(`   身份 UID:  ${config.uid.slice(0, 12)}...`);
   console.log(`   平台地址:  ${config.registry}${config.contexts.metrics}/`);
   console.log(`\n   Claude Code 会话结束后,数据自动上报到上述地址。`);

package/src/logquery.mjs

@@ -24,32 +24,12 @@ import fs from 'node:fs';
 import path from 'node:path';
 import os from 'node:os';
 import readline from 'node:readline';
+import { load, save, getEs, setEs, CONFIG_PATH } from './shared/config.mjs';
 
-const TOOLKIT_DIR = path.join(os.homedir(), '.toolkit');
-const CONFIG_PATH = path.join(TOOLKIT_DIR, 'config.json');
-
-// ── 配置 ──────────────────────────────────────────────
-function loadConfig() {
-  try { return JSON.parse(fs.readFileSync(CONFIG_PATH, 'utf-8')); }
-  catch { return {}; }
-}
-
-function saveConfig(config) {
-  fs.mkdirSync(TOOLKIT_DIR, { recursive: true });
-  fs.writeFileSync(CONFIG_PATH, JSON.stringify(config, null, 2));
-}
-
-function getEsConfig() {
-  const config = loadConfig();
-  return {
-    url: config.es?.url || '',
-    index: config.es?.index || 'plume_log_run_*',
-    app: config.es?.app || '',
-    user: config.es?.user || '',
-    pass: config.es?.pass || '',
-    defaults: { level: 'ERROR', window: 5, hours: 1 },
-  };
-}
+// ── 配置(走 shared/config.mjs)─────────────────────────
+const loadConfig = load;
+const saveConfig = save;
+const getEsConfig = getEs;
 
 // ── 向导 ──────────────────────────────────────────────
 async function ask(rl, prompt, def) {

package/src/shared/config.mjs

@@ -0,0 +1,125 @@
+/**
+ * shared/config.mjs — 统一配置管理(~/.toolkit/config.json)
+ *
+ * 所有 toolkit 工具(install/flush/config/status/logquery)共用。
+ * zentao 仍用独立的 ~/.zentao-cli/.env(向后兼容)。
+ */
+import fs from 'node:fs';
+import path from 'node:path';
+import os from 'node:os';
+
+export const TOOLKIT_DIR = process.env.TOOLKIT_HOME || path.join(os.homedir(), '.toolkit');
+export const CONFIG_PATH = path.join(TOOLKIT_DIR, 'config.json');
+export const UPLOADED_PATH = path.join(TOOLKIT_DIR, 'uploaded.json');
+export const LOG_DIR = path.join(TOOLKIT_DIR, 'logs');
+
+/** 读全部配置。文件不存在返回 {}。 */
+export function load() {
+  try { return JSON.parse(fs.readFileSync(CONFIG_PATH, 'utf-8')); }
+  catch { return {}; }
+}
+
+/** 写全部配置(自动建目录)。 */
+export function save(config) {
+  fs.mkdirSync(TOOLKIT_DIR, { recursive: true });
+  fs.writeFileSync(CONFIG_PATH, JSON.stringify(config, null, 2));
+}
+
+/**
+ * 取单个配置项。
+ * @param {string} key - 顶层 key(registry / uid / project-filter / es / ...)
+ * @returns {any}
+ */
+export function get(key) {
+  return load()[key];
+}
+
+/**
+ * 设置单个配置项。
+ * project-filter 特殊处理:逗号分隔字符串 → 数组。
+ * registry 特殊处理:去尾部 /。
+ * @param {string} key
+ * @param {string} value
+ */
+export function set(key, value) {
+  const config = load();
+  if (key === 'project-filter') {
+    config['project-filter'] = String(value).split(',').map(s => s.trim()).filter(Boolean);
+  } else if (key === 'registry') {
+    config.registry = String(value).replace(/\/$/, '');
+  } else {
+    config[key] = value;
+  }
+  save(config);
+  return config[key];
+}
+
+/** 删除单个配置项。project-filter 置空数组,其他 delete。 */
+export function unset(key) {
+  const config = load();
+  if (key === 'project-filter') {
+    config['project-filter'] = [];
+  } else {
+    delete config[key];
+  }
+  save(config);
+}
+
+/** 读取 ES 配置子段(给 log-query 用)。 */
+export function getEs() {
+  const es = load().es || {};
+  return {
+    url: es.url || '',
+    index: es.index || 'plume_log_run_*',
+    app: es.app || '',
+    user: es.user || '',
+    pass: es.pass || '',
+    defaults: { level: 'ERROR', window: 5, hours: 1 },
+  };
+}
+
+/** 写入 ES 配置子段(给 log-query init 用)。 */
+export function setEs(partial) {
+  const config = load();
+  config.es = { ...(config.es || {}), ...partial };
+  save(config);
+  return config.es;
+}
+
+// ── zentao 段 ────────────────────────────────────────
+// 键名映射:JSON camelCase ↔ .env ZENTAO_UPPER_CASE
+const ZENTAO_KEY_MAP = {
+  'url': 'ZENTAO_URL',
+  'username': 'ZENTAO_USERNAME',
+  'password': 'ZENTAO_PASSWORD',
+  'default-project': 'ZENTAO_DEFAULT_PROJECT',
+  'token-ttl': 'ZENTAO_TOKEN_TTL',
+  'cache-stale-ms': 'ZENTAO_CACHE_STALE_MS',
+};
+
+/** 读 zentao 段(给 zentao CLI 用)。 */
+export function getZentao() {
+  return load().zentao || {};
+}
+
+/** 设置 zentao 段的单个 key。 */
+export function setZentao(key, value) {
+  const config = load();
+  if (!config.zentao) config.zentao = {};
+  config.zentao[key] = value;
+  save(config);
+  return config.zentao[key];
+}
+
+/** 删除 zentao 段的单个 key。 */
+export function unsetZentao(key) {
+  const config = load();
+  if (config.zentao) {
+    delete config.zentao[key];
+    save(config);
+  }
+}
+
+/** 导出键名映射(给 zentao 迁移用)。 */
+export { ZENTAO_KEY_MAP };
+