tools-cc 1.0.10 → 1.0.12

package/AGENTS.md

@@ -1,93 +1,116 @@
-# tools-cc 项目上下文
+# tools-cc
 
-## 项目概述
+CLI 工具，用于统一管理多个 AI 编程工具（iflow、claude、codebuddy、opencode、codex 等）的 skills/commands/agents/rules 配置。通过符号链接机制，避免在多个工具间重复配置。
 
-tools-cc 是一个 CLI 工具，用于统一管理多个 AI 编程工具（iflow、claude、codebuddy、opencode 等）的 skills/commands/agents 配置。通过符号链接机制，避免在多个工具间重复配置。
+## 快速命令
 
-## 技术栈
+```bash
+# 安装依赖
+npm install
 
-- **语言**: TypeScript (ES2020, strict mode)
-- **CLI 框架**: Commander.js
-- **文件操作**: fs-extra
-- **终端输出**: chalk
-- **交互式命令**: inquirer
-- **测试框架**: vitest
-- **运行时**: Node.js (CommonJS)
+# 开发模式运行
+npm run dev
+
+# 编译 TypeScript
+npm run build
+
+# 运行测试
+npm run test:run
+```
 
 ## 项目结构
 
 ```
-tools-cc/
-├── src/
-│   ├── index.ts          # CLI 入口，命令注册
-│   ├── commands/         # CLI 命令处理器
-│   │   ├── config.ts     # 配置管理命令
-│   │   ├── help.ts       # 帮助信息
-│   │   ├── source.ts     # 源管理命令
-│   │   └── use.ts        # 项目使用命令
-│   ├── core/             # 核心业务逻辑
-│   │   ├── config.ts     # 配置读写
-│   │   ├── manifest.ts   # manifest.json 解析
-│   │   ├── project.ts    # 项目管理
-│   │   ├── source.ts     # 源管理
-│   │   └── symlink.ts    # 符号链接创建
-│   ├── types/            # TypeScript 类型定义
-│   │   └── config.ts     # 核心接口定义
-│   └── utils/
-│       └── path.ts       # 路径常量和工具函数
-├── tests/                # 测试文件
-│   ├── core/             # 核心模块测试
-│   └── fixtures/         # 测试固件
-└── dist/                 # 编译输出
+src/
+├── index.ts           # CLI 入口，Commander.js 命令注册
+├── commands/         # 命令处理器
+│   ├── config.ts     # 配置管理命令
+│   ├── source.ts     # 源管理命令
+│   ├── use.ts        # 项目使用命令
+│   ├── template.ts   # 模板管理命令
+│   ├── export.ts     # 导出命令
+│   └── help.ts       # 帮助信息
+├── core/             # 核心业务逻辑
+│   ├── config.ts     # 配置读写
+│   ├── manifest.ts   # manifest.json 解析
+│   ├── project.ts    # 项目管理
+│   ├── source.ts     # 源管理
+│   ├── symlink.ts    # 符号链接创建
+│   └── template.ts   # 模板管理
+├── types/
+│   └── config.ts     # TypeScript 类型定义
+└── utils/
+    └── path.ts       # 路径工具函数
 ```
 
-## 构建和运行
+## 架构设计
 
-```bash
-# 安装依赖
-npm install
+### 数据流
 
-# 开发模式运行
-npm run dev
+1. **全局配置** (`~/.tools-cc/config.json`) → 存储配置源位置和源列表
+2. **源存储** (`~/.tools-cc/sources/`) → 存储克隆/引用的配置源
+3. **项目配置** (`项目/.toolscc/config.json`) → 记录项目中启用的源和选择
 
-# 编译 TypeScript
-npm run build
+### 核心模块
 
-# 运行编译后的代码
-npm start
+- **config**: 读写全局配置，管理 sourcesDir
+- **source**: 添加/移除/更新配置源，支持 git clone 和本地路径
+- **project**: 项目初始化，使用/移除源，符号链接管理
+- **manifest**: 解析源的 manifest.json，支持自动扫描目录结构
+- **template**: 模板保存和应用
 
-# 运行测试
-npm test
+### 配置文件
 
-# 运行测试（单次）
-npm run test:run
+| 作用域 | 路径 | 说明 |
+|--------|------|------|
+| 全局 | `~/.tools-cc/config.json` | 源目录和源列表 |
+| 项目 | `.toolscc/config.json` | 启用的源和链接 |
+| 模板 | `~/.tools-cc/templates/` | 保存的项目配置 |
+
+## 命令速查
 
-# 全局安装（开发）
-npm link
+### 源管理 (全局)
+
+```bash
+tools-cc -s add <name> <path-or-url>  # 添加源
+tools-cc -s list                      # 列出源
+tools-cc -s remove <name>             # 移除源
+tools-cc -s update [name]            # git pull 更新
+tools-cc -s scan                     # 扫描目录发现源
 ```
 
-## 核心命令
+### 项目命令
 
-### 全局配置源管理
-- `tools-cc -s add <name> <path-or-url>` - 添加配置源
-- `tools-cc -s list` - 列出所有配置源
-- `tools-cc -s remove <name>` - 移除配置源
-- `tools-cc -s update [name]` - git pull 更新源代码
-- `tools-cc -s scan` - 扫描目录发现新源
+```bash
+tools-cc use [sources...]              # 启用源（支持部分导入）
+tools-cc use my-skills -p iflow claude # 指定工具链接
+tools-cc use source:skills/xxx        # 部分导入
+tools-cc use -c config.json            # 从文件导入
+tools-cc update [sources...]          # 同步源内容
+tools-cc list                          # 列出已启用源
+tools-cc rm <source>                   # 移除源
+tools-cc status                        # 查看项目状态
+```
 
-### 项目配置
-- `tools-cc use [sources...] [-p tools...]` - 启用配置源并创建符号链接
-- `tools-cc update [sources...]` - 同步源内容到项目
-- `tools-cc list` - 列出已启用的配置源
-- `tools-cc rm <source>` - 禁用配置源
-- `tools-cc status` - 查看项目状态
+### 模板命令
 
-### 配置管理
-- `tools-cc config set <key> <value>` - 设置配置
-- `tools-cc config get <key>` - 获取配置
-- `tools-cc config list` - 查看完整配置
+```bash
+tools-cc template save [-n <name>]  # 保存为模板
+tools-cc template list               # 列出模板
+tools-cc template rm <name>          # 删除模板
+tools-cc template use [name]         # 应用模板
+tools-cc template use -p iflow       # 应用并指定工具
+```
 
-## 支持的 AI 工具
+### 配置命令
+
+```bash
+tools-cc -c set <key> <value>  # 设置配置
+tools-cc -c get <key>          # 获取配置
+tools-cc config list          # 查看全局配置
+```
+
+## 支持的工具
 
 | 工具 | 链接名称 |
 |------|----------|
@@ -95,14 +118,10 @@ npm link
 | claude | `.claude` |
 | codebuddy | `.codebuddy` |
 | opencode | `.opencode` |
+| codex | `.codex` |
+| qoder | `.qoder` |
 
-## 配置文件位置
-
-- **全局配置**: `~/.tools-cc/config.json`
-- **项目配置**: `项目/.toolscc/config.json`
-- **源存储目录**: `~/.tools-cc/sources`（可配置）
-
-## 核心类型
+## 类型定义
 
 ```typescript
 // 源配置
@@ -112,53 +131,42 @@ interface SourceConfig {
   path?: string;
 }
 
-// 全局配置
-interface GlobalConfig {
-  sourcesDir: string;
-  sources: Record<string, SourceConfig>;
+// 源选择配置
+interface SourceSelection {
+  skills: string[];   // ['*'] 或 ['skill-a', 'skill-b']
+  commands: string[];
+  agents: string[];
+  rules: string[];
 }
 
 // 项目配置
 interface ProjectConfig {
-  sources: string[];
+  sources: Record<string, SourceSelection>;
   links: string[];
 }
 
-// Manifest 文件
+// Manifest
 interface Manifest {
   name: string;
   version: string;
   skills?: string[];
   commands?: string[];
   agents?: string[];
+  rules?: string[];
 }
 ```
 
 ## 开发约定
 
-### 代码风格
-- 使用 TypeScript strict 模式
-- 异步函数使用 async/await
-- 文件操作使用 fs-extra
-- 命令处理函数命名：`handle*`
-
-### 测试
-- 测试文件放在 `tests/` 目录，镜像 `src/` 结构
-- 使用 vitest 框架
-- 测试固件放在 `tests/fixtures/`
-
-### 命令添加
-1. 在 `src/commands/` 创建或修改命令处理文件
-2. 在 `src/index.ts` 注册新命令
-3. 添加相应的测试
-
-### 文档更新 [CHANGELOG.md](CHANGELOG.md)[README.md](README.md)
-- 更新文档时，请确保命令描述清晰、准确，并使用一致的格式
-- 添加新命令时，请更新命令列表和描述
-- 修改现有命令时，请更新相关命令的描述
+- **TypeScript**: ES2020 target, CommonJS, strict mode
+- **异步**: 使用 async/await
+- **文件操作**: fs-extra
+- **CLI**: Commander.js
+- **测试**: vitest
+- **命令处理**: `handle*` 命名约定
 
 ## 注意事项
 
-- 此项目运行在 Windows 系统，注意路径分隔符兼容性
-- 符号链接在 Windows 上可能需要管理员权限
-- 全局配置目录位于用户主目录下的 `.tools-cc`
+- 运行在 Windows，注意路径分隔符兼容性
+- Windows 上使用 junction 创建符号链接（不需要管理员权限）
+- 全局配置目录: `~/.tools-cc`

package/CHANGELOG.md

@@ -2,6 +2,16 @@
 
 本项目的所有重要变更都将记录在此文件中。
 
+## [1.0.12] - 2026-03-23
+
+### Added
+- 添加 npm 包版本发布使用指南文档 (RELEASING.md)
+
+## [1.0.11] - 2026-03-06
+
+### Changed
+- 完善项目配置的默认值和字段规范化
+
 ## [1.0.10] - 2026-03-05
 
 ### Added

package/CHANGELOG_en.md

@@ -2,6 +2,11 @@
 
 All notable changes to this project will be documented in this file.
 
+## [1.0.11] - 2026-03-06
+
+### Changed
+- Improved default values and field normalization for project configuration
+
 ## [1.0.10] - 2026-03-05
 
 ### Added

package/dist/commands/use.js

@@ -24,7 +24,8 @@ const SUPPORTED_TOOLS = {
     claude: '.claude',
     codebuddy: '.codebuddy',
     opencode: '.opencode',
-    codex: '.codex'
+    codex: '.codex',
+    qoder: '.qoder'
 };
 /**
  * 处理 use 命令

package/dist/types/config.d.ts

@@ -37,6 +37,7 @@ export declare function isSourceSelection(value: unknown): value is SourceSelect
 /**
  * 将旧版项目配置转换为新版格式
  * 如果 sources 是字符串数组，转换为 Record 格式，每个源默认导入全部内容
+ * 同时确保所有 SourceSelection 对象字段完整
  */
 export declare function normalizeProjectConfig(config: LegacyProjectConfig | ProjectConfig): ProjectConfig;
 export interface Manifest {

package/dist/types/config.js

@@ -14,23 +14,44 @@ function isSourceSelection(value) {
         Array.isArray(obj.agents) &&
         Array.isArray(obj.rules));
 }
+/**
+ * 默认选择配置 - 导入所有内容
+ */
+const DEFAULT_SOURCE_SELECTION = {
+    skills: ['*'],
+    commands: ['*'],
+    agents: ['*'],
+    rules: ['*']
+};
+/**
+ * 确保 SourceSelection 对象字段完整
+ */
+function normalizeSourceSelection(selection) {
+    return {
+        skills: selection?.skills ?? DEFAULT_SOURCE_SELECTION.skills,
+        commands: selection?.commands ?? DEFAULT_SOURCE_SELECTION.commands,
+        agents: selection?.agents ?? DEFAULT_SOURCE_SELECTION.agents,
+        rules: selection?.rules ?? DEFAULT_SOURCE_SELECTION.rules
+    };
+}
 /**
  * 将旧版项目配置转换为新版格式
  * 如果 sources 是字符串数组，转换为 Record 格式，每个源默认导入全部内容
+ * 同时确保所有 SourceSelection 对象字段完整
  */
 function normalizeProjectConfig(config) {
     // If sources is an array, convert to new format
     if (Array.isArray(config.sources)) {
         const newSources = {};
         for (const sourceName of config.sources) {
-            newSources[sourceName] = {
-                skills: ['*'],
-                commands: ['*'],
-                agents: ['*'],
-                rules: ['*']
-            };
+            newSources[sourceName] = { ...DEFAULT_SOURCE_SELECTION };
         }
         return { sources: newSources, links: config.links };
     }
-    return config;
+    // If sources is an object, ensure all SourceSelection fields are complete
+    const normalizedSources = {};
+    for (const [sourceName, selection] of Object.entries(config.sources)) {
+        normalizedSources[sourceName] = normalizeSourceSelection(selection);
+    }
+    return { sources: normalizedSources, links: config.links };
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "tools-cc",
-  "version": "1.0.10",
+  "version": "1.0.12",
   "description": "tools-cc [options] <command> [args]",
   "main": "index.js",
   "directories": {

package/skills/releasing/SKILL.md

@@ -0,0 +1,217 @@
+---
+name: releasing
+description: Use when preparing a new version release for npm packages with GitHub releases. Handles version bump, changelog updates, git tags, npm publish, and GitHub release creation.
+---
+
+# Releasing
+
+## Overview
+
+版本发布助手，自动化 npm 包发布流程：版本号更新 → 文档同步 → Git Tag → GitHub Release → 提醒用户 npm 发布。
+
+**核心原则：每个步骤必须验证成功，失败立即停止。**
+
+## When to Use
+
+- 准备发布新版本时
+- 需要更新 CHANGELOG 时
+- 需要 npm publish 时
+- 需要 GitHub release 时
+
+**NOT for:**
+- Hot fix 紧急修复（需要特殊流程）
+- 私有包发布
+- 非 npm 项目
+
+## Release Workflow
+
+```dot
+digraph release {
+    rankdir=TB;
+    
+    "Start" [shape=ellipse];
+    "Git Status Clean?" [shape=diamond];
+    "Tests Pass?" [shape=diamond];
+    "Choose Version" [shape=box];
+    "Update package.json" [shape=box];
+    "Update CHANGELOG" [shape=box];
+    "Update README" [shape=box];
+    "Build" [shape=box];
+    "Git Commit" [shape=box];
+    "Git Pull" [shape=box];
+    "Git Tag" [shape=box];
+    "Push Tag" [shape=box];
+    "gh release" [shape=box];
+    "Done (remind npm publish)" [shape=ellipse];
+    "STOP: Fix Issues" [shape=box style=filled fillcolor=red];
+    
+    "Start" -> "Git Status Clean?";
+    "Git Status Clean?" -> "Tests Pass?" [label="yes"];
+    "Git Status Clean?" -> "STOP: Fix Issues" [label="no"];
+    "Tests Pass?" -> "Choose Version" [label="yes"];
+    "Tests Pass?" -> "STOP: Fix Issues" [label="no"];
+    "Choose Version" -> "Update package.json";
+    "Update package.json" -> "Update CHANGELOG";
+    "Update CHANGELOG" -> "Update README";
+    "Update README" -> "Build";
+    "Build" -> "Git Commit";
+    "Git Commit" -> "Git Pull";
+    "Git Pull" -> "Git Tag";
+    "Git Tag" -> "Push Tag";
+    "Push Tag" -> "gh release";
+    "gh release" -> "Done (remind npm publish)";
+}
+```
+
+## Version Selection
+
+| Type | Example | When to Use |
+|------|---------|-------------|
+| major | 1.0.0 → 2.0.0 | Breaking changes, incompatible API |
+| minor | 1.0.0 → 1.1.0 | New features, backwards compatible |
+| patch | 1.0.0 → 1.0.1 | Bug fixes, backwards compatible |
+
+## Step Details
+
+### 1. Pre-flight Checks
+
+**MUST verify before starting:**
+
+```bash
+# 检查 git 状态
+git status --porcelain
+# 如果有输出，必须先处理
+
+# 检查测试
+npm test
+# 必须全部通过
+```
+
+### 2. Version Bump
+
+```bash
+# 方式一：npm version 命令（自动 git commit + tag）
+npm version patch|minor|major
+
+# 方式二：手动更新 package.json（需要手动 commit）
+# 编辑 package.json 中的 version 字段
+```
+
+### 3. Update CHANGELOG
+
+添加新版本条目到 CHANGELOG.md 和 CHANGELOG_en.md：
+
+```markdown
+## [X.Y.Z] - YYYY-MM-DD
+
+### Added
+- 新增功能描述
+
+### Changed
+- 变更描述
+
+### Fixed
+- 修复描述
+```
+
+### 4. Update README
+
+检查 README.md 和 README_en.md 中是否有版本相关内容需要更新：
+- 安装命令中的版本号
+- 更新日志链接
+- 其他版本引用
+
+### 5. Build & Commit
+
+```bash
+npm run build
+git add .
+git commit -m "chore: release v$VERSION"
+```
+
+### 6. Sync & Tag
+
+```bash
+# 先 pull 最新代码
+git pull
+
+# 创建 tag
+git tag v$VERSION
+
+# push commit 和 tag（使用实际分支名，如 master/main）
+git push github <branch>
+git push github v$VERSION
+```
+
+### 7. GitHub Release
+
+```bash
+gh release create v$VERSION --title v$VERSION --generate-notes
+```
+
+### 8. npm Publish (最后提醒用户)
+
+**完成所有自动化步骤后，在最终消息中提醒用户手动执行 npm publish。**
+
+**不要使用 ask_user_question 工具询问，直接在完成消息中提示即可。**
+
+提示格式：
+```
+**发布完成！请手动执行 `npm publish` 完成 npm 发布。**
+```
+
+**用户执行前确认：**
+- 已登录 npm (`npm whoami`)
+- 有发布权限
+- 网络连接正常
+
+## Common Mistakes
+
+| Mistake | Consequence | Prevention |
+|---------|-------------|------------|
+| 跳过 git status 检查 | 发布错误代码 | 必须检查，有输出就停止 |
+| 跳过测试 | 发布有 bug 的版本 | 测试必须通过 |
+| 忘记更新 CHANGELOG | 用户不知道变更内容 | 更新后必须验证格式 |
+| 忘记 build | 发布旧代码 | build 后检查 dist 目录 |
+| 忘记 git pull | tag 冲突或覆盖他人提交 | 创建 tag 前必须 pull |
+| 先 npm publish 再 tag/gh release | 无法回退 | 严格遵守顺序：先 tag 和 gh release，最后提醒 npm publish |
+| 版本号格式错误 | tag 创建失败 | 使用 semver 格式 |
+
+## Red Flags - STOP and Fix
+
+- 有未提交的更改
+- 测试失败
+- CHANGELOG 未更新
+- 版本号已存在
+- npm 未登录
+- 网络连接问题
+
+**任何步骤失败，立即停止，不要继续。**
+
+## Rationalization Table
+
+| Excuse | Reality |
+|--------|---------|
+| "测试之前跑过，肯定没问题" | 代码变了，测试必须重跑 |
+| "简单版本，不需要更新 CHANGELOG" | 用户需要知道变更内容 |
+| "先发布再说，文档后面补" | 忘记补的概率 99% |
+| "跳过 pull，本地肯定是最新的" | 远程可能有其他提交 |
+| "手动测试过了，不需要跑测试" | 手动测试覆盖不全 |
+| "npm version 命令会自动处理" | 不会自动更新 CHANGELOG/README |
+| "先 npm publish，tag 后面补" | 发布失败无法回退，顺序应为 tag → gh release → npm publish |
+
+## Quick Reference
+
+```bash
+# 完整发布流程
+git status --porcelain    # 1. 检查状态
+npm test                  # 2. 运行测试
+# 更新版本号、CHANGELOG、README
+npm run build             # 3. 构建
+git add . && git commit -m "chore: release vX.Y.Z"
+git pull                  # 4. 同步远程
+git tag vX.Y.Z            # 5. 创建 tag
+git push github master && git push github vX.Y.Z
+gh release create vX.Y.Z --title vX.Y.Z --generate-notes  # 6. GitHub release
+# 7. 在完成消息中提醒用户: 请手动执行 npm publish
+```

package/src/commands/use.ts

@@ -16,7 +16,8 @@ const SUPPORTED_TOOLS: Record<string, string> = {
   claude: '.claude',
   codebuddy: '.codebuddy',
   opencode: '.opencode',
-  codex: '.codex'
+  codex: '.codex',
+  qoder: '.qoder'
 };
 
 /**

package/src/types/config.ts

@@ -49,9 +49,32 @@ export function isSourceSelection(value: unknown): value is SourceSelection {
   );
 }
 
+/**
+ * 默认选择配置 - 导入所有内容
+ */
+const DEFAULT_SOURCE_SELECTION: SourceSelection = {
+  skills: ['*'],
+  commands: ['*'],
+  agents: ['*'],
+  rules: ['*']
+};
+
+/**
+ * 确保 SourceSelection 对象字段完整
+ */
+function normalizeSourceSelection(selection: Partial<SourceSelection> | undefined): SourceSelection {
+  return {
+    skills: selection?.skills ?? DEFAULT_SOURCE_SELECTION.skills,
+    commands: selection?.commands ?? DEFAULT_SOURCE_SELECTION.commands,
+    agents: selection?.agents ?? DEFAULT_SOURCE_SELECTION.agents,
+    rules: selection?.rules ?? DEFAULT_SOURCE_SELECTION.rules
+  };
+}
+
 /**
  * 将旧版项目配置转换为新版格式
  * 如果 sources 是字符串数组，转换为 Record 格式，每个源默认导入全部内容
+ * 同时确保所有 SourceSelection 对象字段完整
  */
 export function normalizeProjectConfig(
   config: LegacyProjectConfig | ProjectConfig
@@ -60,16 +83,18 @@ export function normalizeProjectConfig(
   if (Array.isArray(config.sources)) {
     const newSources: Record<string, SourceSelection> = {};
     for (const sourceName of config.sources) {
-      newSources[sourceName] = {
-        skills: ['*'],
-        commands: ['*'],
-        agents: ['*'],
-        rules: ['*']
-      };
+      newSources[sourceName] = { ...DEFAULT_SOURCE_SELECTION };
     }
     return { sources: newSources, links: config.links };
   }
-  return config as ProjectConfig;
+  
+  // If sources is an object, ensure all SourceSelection fields are complete
+  const normalizedSources: Record<string, SourceSelection> = {};
+  for (const [sourceName, selection] of Object.entries(config.sources as Record<string, Partial<SourceSelection>>)) {
+    normalizedSources[sourceName] = normalizeSourceSelection(selection);
+  }
+  
+  return { sources: normalizedSources, links: config.links };
 }
 
 export interface Manifest {