ccgx-workflow 1.0.0 → 1.0.1

package/templates/scripts/invoke-model.mjs

@@ -186,6 +186,61 @@ function lookPath(cmd, opts = {}) {
   return cmd; // let spawn surface ENOENT
 }
 
+// Resolve `cmd` against PATH (POSIX) or PATH+PATHEXT (Windows).
+// Returns null when the binary is not found, giving callers a chance to emit
+// a friendly install hint before spawn raises ENOENT.
+function resolveOnPath(cmd, opts = {}) {
+  const env = opts.env || process.env;
+  const platform = opts.platform || process.platform;
+  const stat = opts.statFn || statSync;
+  if (path.isAbsolute(cmd) || cmd.includes('/') || (platform === 'win32' && cmd.includes('\\'))) {
+    try { const info = stat(cmd); if (info && info.isFile && info.isFile()) return cmd; }
+    catch { /* fallthrough */ }
+    return null;
+  }
+  if (platform === 'win32') {
+    const resolved = lookPath(cmd, opts);
+    return resolved !== cmd ? resolved : null;
+  }
+  const dirs = (env.PATH || '').split(':').filter(Boolean);
+  for (const dir of dirs) {
+    const full = path.join(dir, cmd);
+    try { const info = stat(full); if (info && info.isFile && info.isFile()) return full; }
+    catch { /* keep scanning */ }
+  }
+  return null;
+}
+
+// Print install guidance and exit 127 when the requested backend CLI is not
+// on PATH. Prefers Claude Code plugins (one-click) over manual CLI install.
+function exitMissingBackend(backend) {
+  const pluginInstall = backend === 'codex'
+    ? '/plugins install codex@openai-codex'
+    : backend === 'gemini'
+      ? '/plugins install gemini@google-gemini'
+      : null;
+  const npmInstall = backend === 'codex'
+    ? 'npm i -g @openai/codex'
+    : backend === 'gemini'
+      ? 'npm i -g @google/gemini-cli'
+      : null;
+  process.stderr.write([
+    '',
+    `❌ ccgx-workflow fallback: '${backend}' CLI not found on PATH.`,
+    '',
+    'Pick one of:',
+    pluginInstall
+      ? `  • Plugin (recommended): in Claude Code run  ${pluginInstall}`
+      : `  • Plugin route is unavailable for backend "${backend}".`,
+    npmInstall
+      ? `  • CLI fallback: ${npmInstall}   then  ${backend} login / auth`
+      : '',
+    '',
+    'After installing, start a new Claude Code session.',
+    '',
+  ].filter(Boolean).join('\n') + '\n');
+}
+
 function expandHome(p) {
   if (typeof p !== 'string') return p;
   if (p === '~') return homedir();
@@ -706,6 +761,15 @@ async function main() {
 
   const { command, args } = backendCommandAndArgs(cfg, targetArg);
 
+  // Friendly fail when the backend CLI is not installed.
+  // Skip for absolute paths — those are already explicit user intent.
+  if (!path.isAbsolute(command) && !command.includes('/') && !command.includes('\\')) {
+    if (resolveOnPath(command) === null) {
+      exitMissingBackend(cfg.backend);
+      return 127;
+    }
+  }
+
   // Startup banner (main.go:432)
   process.stderr.write(
     `[${WRAPPER_NAME}]\n` +

package/templates/skills/domains/ai/SKILL.md

@@ -1,35 +1,35 @@
----
-name: ai
-description: AI/LLM 能力索引（Agent 开发、LLM 安全、RAG、Prompt 工程）。
-license: MIT
-user-invocable: false
-disable-model-invocation: false
-context: fork
----
-
-# 丹鼎秘典 · AI/LLM 能力中枢
-
-## 能力矩阵
-
-| Skill | 定位 | 核心能力 |
-|-------|------|----------|
-| [agent-dev](agent-dev.md) | Agent 开发 | 多 Agent 编排、工具调用、RAG |
-| [llm-security](llm-security.md) | LLM 安全 | Prompt 注入、越狱防护、输出安全 |
-| [rag-system](rag-system.md) | RAG 系统 | 向量数据库、检索策略、重排算法 |
-| [prompt-and-eval](prompt-and-eval.md) | Prompt 工程与模型评估 | Few-shot、CoT、ReAct、RAGAS、LLM-as-Judge |
-
-## AI 工程原则
-
-```yaml
-设计原则:
-  - 人机协作，AI 增强而非替代
-  - 可解释性优先
-  - 安全边界明确
-  - 渐进式自主
-
-开发原则:
-  - Prompt 即代码，需版本控制
-  - 输入输出都需验证
-  - 成本与效果平衡
-  - 持续评估与迭代
-```
+---
+name: ai
+description: AI/LLM 能力索引（Agent 开发、LLM 安全、RAG、Prompt 工程）。
+license: MIT
+user-invocable: false
+disable-model-invocation: false
+context: fork
+---
+
+# 丹鼎秘典 · AI/LLM 能力中枢
+
+## 能力矩阵
+
+| Skill | 定位 | 核心能力 |
+|-------|------|----------|
+| [agent-dev](agent-dev.md) | Agent 开发 | 多 Agent 编排、工具调用、RAG |
+| [llm-security](llm-security.md) | LLM 安全 | Prompt 注入、越狱防护、输出安全 |
+| [rag-system](rag-system.md) | RAG 系统 | 向量数据库、检索策略、重排算法 |
+| [prompt-and-eval](prompt-and-eval.md) | Prompt 工程与模型评估 | Few-shot、CoT、ReAct、RAGAS、LLM-as-Judge |
+
+## AI 工程原则
+
+```yaml
+设计原则:
+  - 人机协作，AI 增强而非替代
+  - 可解释性优先
+  - 安全边界明确
+  - 渐进式自主
+
+开发原则:
+  - Prompt 即代码，需版本控制
+  - 输入输出都需验证
+  - 成本与效果平衡
+  - 持续评估与迭代
+```

package/templates/skills/domains/ai/agent-dev.md

@@ -1,242 +1,242 @@
----
-name: agent-dev
-description: AI Agent 开发。多 Agent 编排、工具调用、RAG 系统、Prompt 工程。当用户提到 Agent、RAG、Prompt、LangChain、向量数据库时使用。
----
-
-# 🔮 丹鼎秘典 · AI Agent 开发
-
-
-## Agent 架构
-
-```
-┌─────────────────────────────────────────────────────────────┐
-│                      Agent 系统                              │
-├─────────────────────────────────────────────────────────────┤
-│  用户输入 → 意图理解 → 规划 → 执行 → 反思 → 输出            │
-│              │          │      │      │                      │
-│           Prompt     Planner  Tools  Memory                  │
-└─────────────────────────────────────────────────────────────┘
-```
-
-## 核心组件
-
-### 1. Prompt 工程
-
-```yaml
-结构化 Prompt:
-  - System: 角色定义、能力边界、行为规范
-  - Context: 背景信息、相关知识
-  - Task: 具体任务、输出格式
-  - Examples: Few-shot 示例
-
-技巧:
-  - 明确角色和边界
-  - 分步骤引导思考
-  - 提供输出格式示例
-  - 设置安全护栏
-```
-
-### 2. 工具调用
-
-```python
-# 工具定义
-tools = [
-    {
-        "name": "search",
-        "description": "搜索知识库",
-        "parameters": {
-            "type": "object",
-            "properties": {
-                "query": {"type": "string", "description": "搜索关键词"}
-            },
-            "required": ["query"]
-        }
-    }
-]
-
-# 工具执行
-def execute_tool(name: str, args: dict) -> str:
-    if name == "search":
-        return search_knowledge_base(args["query"])
-    raise ValueError(f"Unknown tool: {name}")
-```
-
-### 3. 记忆系统
-
-```yaml
-短期记忆:
-  - 对话历史
-  - 当前任务上下文
-  - 工具调用结果
-
-长期记忆:
-  - 向量数据库存储
-  - 用户偏好
-  - 历史交互摘要
-
-记忆管理:
-  - 滑动窗口
-  - 摘要压缩
-  - 重要性排序
-```
-
-## RAG 系统
-
-### 架构
-
-```
-文档 → 分块 → 嵌入 → 向量库
-                        ↓
-查询 → 嵌入 → 检索 → 重排序 → 生成
-```
-
-### 实现
-
-```python
-from langchain.text_splitter import RecursiveCharacterTextSplitter
-from langchain.embeddings import OpenAIEmbeddings
-from langchain.vectorstores import Chroma
-
-# 文档处理
-splitter = RecursiveCharacterTextSplitter(
-    chunk_size=1000,
-    chunk_overlap=200,
-    separators=["\n\n", "\n", "。", "，", " "]
-)
-chunks = splitter.split_documents(documents)
-
-# 向量存储
-embeddings = OpenAIEmbeddings()
-vectorstore = Chroma.from_documents(chunks, embeddings)
-
-# 检索
-retriever = vectorstore.as_retriever(
-    search_type="mmr",  # 最大边际相关性
-    search_kwargs={"k": 5, "fetch_k": 20}
-)
-```
-
-### 优化策略
-
-```yaml
-分块策略:
-  - 语义分块 vs 固定长度
-  - 重叠避免信息丢失
-  - 保留元数据
-
-检索优化:
-  - 混合检索 (关键词 + 向量)
-  - 重排序 (Reranker)
-  - 查询扩展
-
-生成优化:
-  - 引用来源
-  - 置信度评估
-  - 幻觉检测
-```
-
-## 多 Agent 编排
-
-### 模式
-
-```yaml
-顺序执行:
-  Agent A → Agent B → Agent C
-
-并行执行:
-  Agent A ─┬─→ Agent B ─┬─→ 汇总
-           └─→ Agent C ─┘
-
-层级结构:
-  Orchestrator
-      ├── Planner Agent
-      ├── Executor Agent
-      └── Reviewer Agent
-
-对话式:
-  Agent A ←→ Agent B (多轮交互)
-```
-
-### 实现示例
-
-```python
-class Orchestrator:
-    def __init__(self):
-        self.planner = PlannerAgent()
-        self.executor = ExecutorAgent()
-        self.reviewer = ReviewerAgent()
-
-    async def run(self, task: str) -> str:
-        # 规划
-        plan = await self.planner.plan(task)
-
-        # 执行
-        results = []
-        for step in plan.steps:
-            result = await self.executor.execute(step)
-            results.append(result)
-
-        # 审查
-        final = await self.reviewer.review(task, results)
-        return final
-```
-
-## 评估与监控
-
-```yaml
-评估维度:
-  - 准确性: 答案正确率
-  - 相关性: 检索质量
-  - 完整性: 信息覆盖
-  - 一致性: 多次回答稳定性
-
-监控指标:
-  - 延迟 (P50/P95/P99)
-  - Token 消耗
-  - 工具调用成功率
-  - 用户满意度
-```
-
-## 框架选择
-
-```yaml
-LangChain:
-  - 优点: 生态丰富，组件多
-  - 缺点: 抽象层多，调试难
-  - 适合: 快速原型
-
-LlamaIndex:
-  - 优点: RAG 专精
-  - 缺点: Agent 能力弱
-  - 适合: 知识库应用
-
-原生实现:
-  - 优点: 完全可控
-  - 缺点: 开发成本高
-  - 适合: 生产系统
-```
-
-## 最佳实践
-
-```yaml
-开发:
-  - Prompt 版本控制
-  - 单元测试覆盖
-  - 成本预算控制
-  - 降级策略
-
-部署:
-  - 流式输出
-  - 超时处理
-  - 重试机制
-  - 缓存策略
-
-安全:
-  - 输入验证
-  - 输出过滤
-  - 权限控制
-  - 审计日志
-```
-
----
-
+---
+name: agent-dev
+description: AI Agent 开发。多 Agent 编排、工具调用、RAG 系统、Prompt 工程。当用户提到 Agent、RAG、Prompt、LangChain、向量数据库时使用。
+---
+
+# 🔮 丹鼎秘典 · AI Agent 开发
+
+
+## Agent 架构
+
+```
+┌─────────────────────────────────────────────────────────────┐
+│                      Agent 系统                              │
+├─────────────────────────────────────────────────────────────┤
+│  用户输入 → 意图理解 → 规划 → 执行 → 反思 → 输出            │
+│              │          │      │      │                      │
+│           Prompt     Planner  Tools  Memory                  │
+└─────────────────────────────────────────────────────────────┘
+```
+
+## 核心组件
+
+### 1. Prompt 工程
+
+```yaml
+结构化 Prompt:
+  - System: 角色定义、能力边界、行为规范
+  - Context: 背景信息、相关知识
+  - Task: 具体任务、输出格式
+  - Examples: Few-shot 示例
+
+技巧:
+  - 明确角色和边界
+  - 分步骤引导思考
+  - 提供输出格式示例
+  - 设置安全护栏
+```
+
+### 2. 工具调用
+
+```python
+# 工具定义
+tools = [
+    {
+        "name": "search",
+        "description": "搜索知识库",
+        "parameters": {
+            "type": "object",
+            "properties": {
+                "query": {"type": "string", "description": "搜索关键词"}
+            },
+            "required": ["query"]
+        }
+    }
+]
+
+# 工具执行
+def execute_tool(name: str, args: dict) -> str:
+    if name == "search":
+        return search_knowledge_base(args["query"])
+    raise ValueError(f"Unknown tool: {name}")
+```
+
+### 3. 记忆系统
+
+```yaml
+短期记忆:
+  - 对话历史
+  - 当前任务上下文
+  - 工具调用结果
+
+长期记忆:
+  - 向量数据库存储
+  - 用户偏好
+  - 历史交互摘要
+
+记忆管理:
+  - 滑动窗口
+  - 摘要压缩
+  - 重要性排序
+```
+
+## RAG 系统
+
+### 架构
+
+```
+文档 → 分块 → 嵌入 → 向量库
+                        ↓
+查询 → 嵌入 → 检索 → 重排序 → 生成
+```
+
+### 实现
+
+```python
+from langchain.text_splitter import RecursiveCharacterTextSplitter
+from langchain.embeddings import OpenAIEmbeddings
+from langchain.vectorstores import Chroma
+
+# 文档处理
+splitter = RecursiveCharacterTextSplitter(
+    chunk_size=1000,
+    chunk_overlap=200,
+    separators=["\n\n", "\n", "。", "，", " "]
+)
+chunks = splitter.split_documents(documents)
+
+# 向量存储
+embeddings = OpenAIEmbeddings()
+vectorstore = Chroma.from_documents(chunks, embeddings)
+
+# 检索
+retriever = vectorstore.as_retriever(
+    search_type="mmr",  # 最大边际相关性
+    search_kwargs={"k": 5, "fetch_k": 20}
+)
+```
+
+### 优化策略
+
+```yaml
+分块策略:
+  - 语义分块 vs 固定长度
+  - 重叠避免信息丢失
+  - 保留元数据
+
+检索优化:
+  - 混合检索 (关键词 + 向量)
+  - 重排序 (Reranker)
+  - 查询扩展
+
+生成优化:
+  - 引用来源
+  - 置信度评估
+  - 幻觉检测
+```
+
+## 多 Agent 编排
+
+### 模式
+
+```yaml
+顺序执行:
+  Agent A → Agent B → Agent C
+
+并行执行:
+  Agent A ─┬─→ Agent B ─┬─→ 汇总
+           └─→ Agent C ─┘
+
+层级结构:
+  Orchestrator
+      ├── Planner Agent
+      ├── Executor Agent
+      └── Reviewer Agent
+
+对话式:
+  Agent A ←→ Agent B (多轮交互)
+```
+
+### 实现示例
+
+```python
+class Orchestrator:
+    def __init__(self):
+        self.planner = PlannerAgent()
+        self.executor = ExecutorAgent()
+        self.reviewer = ReviewerAgent()
+
+    async def run(self, task: str) -> str:
+        # 规划
+        plan = await self.planner.plan(task)
+
+        # 执行
+        results = []
+        for step in plan.steps:
+            result = await self.executor.execute(step)
+            results.append(result)
+
+        # 审查
+        final = await self.reviewer.review(task, results)
+        return final
+```
+
+## 评估与监控
+
+```yaml
+评估维度:
+  - 准确性: 答案正确率
+  - 相关性: 检索质量
+  - 完整性: 信息覆盖
+  - 一致性: 多次回答稳定性
+
+监控指标:
+  - 延迟 (P50/P95/P99)
+  - Token 消耗
+  - 工具调用成功率
+  - 用户满意度
+```
+
+## 框架选择
+
+```yaml
+LangChain:
+  - 优点: 生态丰富，组件多
+  - 缺点: 抽象层多，调试难
+  - 适合: 快速原型
+
+LlamaIndex:
+  - 优点: RAG 专精
+  - 缺点: Agent 能力弱
+  - 适合: 知识库应用
+
+原生实现:
+  - 优点: 完全可控
+  - 缺点: 开发成本高
+  - 适合: 生产系统
+```
+
+## 最佳实践
+
+```yaml
+开发:
+  - Prompt 版本控制
+  - 单元测试覆盖
+  - 成本预算控制
+  - 降级策略
+
+部署:
+  - 流式输出
+  - 超时处理
+  - 重试机制
+  - 缓存策略
+
+安全:
+  - 输入验证
+  - 输出过滤
+  - 权限控制
+  - 审计日志
+```
+
+---
+