@pm_zhousl/xinyun-ai-init 1.0.2 → 1.1.0

package/README.md

@@ -24,6 +24,15 @@ npx --yes @pm_zhousl/xinyun-ai-init@latest --force
 
 完整执行要求已经内置在 `xinyun-ai-init/README.md`、`rules/` 和 `templates/` 中。后续不需要复制长提示词，只需要让 AI 读取本地释放出来的 `xinyun-ai-init/README.md`。
 
+CLI 执行时会显示当前版本，并尽量检测 npm 线上最新版本；检测失败不会阻塞初始化。
+
+可选参数：
+
+```bash
+--no-version-check
+--strict-version
+```
+
 ## 维护者发布
 
 发布新版时，在本包目录执行：

package/bin/xinyun-ai-init.js

@@ -1,13 +1,21 @@
 #!/usr/bin/env node
 
 const fs = require("fs");
+const https = require("https");
 const path = require("path");
 
+const packageJson = require("../package.json");
+
 const args = new Set(process.argv.slice(2));
 const force = args.has("--force") || args.has("-f");
+const noVersionCheck = args.has("--no-version-check");
+const strictVersion = args.has("--strict-version");
 const cwd = process.cwd();
 const source = path.resolve(__dirname, "..", "init", "xinyun-ai-init");
 const target = path.join(cwd, "xinyun-ai-init");
+const packageName = packageJson.name;
+const currentVersion = packageJson.version;
+const registryMetadataUrl = "https://registry.npmjs.org/@pm_zhousl%2Fxinyun-ai-init";
 
 function copyDir(src, dest) {
   fs.mkdirSync(dest, { recursive: true });
@@ -22,16 +30,105 @@ function copyDir(src, dest) {
   }
 }
 
-function main() {
+function compareVersions(a, b) {
+  const pa = String(a).split(".").map((part) => Number.parseInt(part, 10) || 0);
+  const pb = String(b).split(".").map((part) => Number.parseInt(part, 10) || 0);
+  const length = Math.max(pa.length, pb.length);
+
+  for (let index = 0; index < length; index += 1) {
+    const av = pa[index] || 0;
+    const bv = pb[index] || 0;
+    if (av > bv) return 1;
+    if (av < bv) return -1;
+  }
+
+  return 0;
+}
+
+function fetchLatestVersion(timeoutMs = 1500) {
+  return new Promise((resolve) => {
+    const request = https.get(
+      registryMetadataUrl,
+      { headers: { Accept: "application/json", "User-Agent": "xinyun-ai-init" } },
+      (response) => {
+        let body = "";
+
+        response.setEncoding("utf8");
+        response.on("data", (chunk) => {
+          body += chunk;
+        });
+        response.on("end", () => {
+          if (response.statusCode < 200 || response.statusCode >= 300) {
+            resolve(null);
+            return;
+          }
+
+          try {
+            const data = JSON.parse(body);
+            resolve(data && data["dist-tags"] ? data["dist-tags"].latest : null);
+          } catch (error) {
+            resolve(null);
+          }
+        });
+      }
+    );
+
+    request.setTimeout(timeoutMs, () => {
+      request.destroy();
+      resolve(null);
+    });
+
+    request.on("error", () => {
+      resolve(null);
+    });
+  });
+}
+
+async function checkVersion() {
+  console.log(`[xinyun-ai-init] Current version: ${currentVersion}`);
+
+  if (noVersionCheck) {
+    console.log("[xinyun-ai-init] Version check skipped.");
+    return true;
+  }
+
+  const latestVersion = await fetchLatestVersion();
+
+  if (!latestVersion) {
+    console.log("[xinyun-ai-init] Could not check latest npm version. Continue with local version.");
+    return true;
+  }
+
+  console.log(`[xinyun-ai-init] Latest version: ${latestVersion}`);
+
+  if (compareVersions(currentVersion, latestVersion) < 0) {
+    console.log("[xinyun-ai-init] A newer version is available. Recommended command:");
+    console.log(`npx --yes ${packageName}@latest --force`);
+
+    if (strictVersion) {
+      console.error("[xinyun-ai-init] Strict version mode is enabled. Stop because local version is outdated.");
+      return false;
+    }
+  }
+
+  return true;
+}
+
+async function main() {
+  const canContinue = await checkVersion();
+  if (!canContinue) {
+    process.exit(1);
+  }
+
   if (!fs.existsSync(source)) {
-    console.error("[xinyun-ai-init] 初始化包缺失：", source);
+    console.error("[xinyun-ai-init] Init package missing:", source);
     process.exit(1);
   }
 
   if (fs.existsSync(target)) {
     if (!force) {
-      console.log("[xinyun-ai-init] 当前目录已存在 xinyun-ai-init/，未覆盖。");
-      console.log("[xinyun-ai-init] 如需覆盖，请执行：npx @pm_zhousl/xinyun-ai-init --force");
+      console.log("[xinyun-ai-init] xinyun-ai-init/ already exists. Skip overwrite.");
+      console.log(`[xinyun-ai-init] To overwrite, run: npx --yes ${packageName}@latest --force`);
       console.log("");
       printNextStep();
       return;
@@ -40,18 +137,21 @@ function main() {
   }
 
   copyDir(source, target);
-  console.log("[xinyun-ai-init] 已生成：", target);
+  console.log("[xinyun-ai-init] Created:", target);
   console.log("");
   printNextStep();
 }
 
 function printNextStep() {
-  console.log("下一步：把下面这句话发给 Codex / Cursor / Claude Code：");
+  console.log("Next step: send this message to Codex / Cursor / Claude Code:");
   console.log("");
   console.log("请执行 `npx --yes @pm_zhousl/xinyun-ai-init@latest --force`，然后读取 `xinyun-ai-init/README.md`，按其中规则初始化或升级当前项目。");
   console.log("");
-  console.log("完整执行要求已经在 xinyun-ai-init/README.md 内，不需要再粘贴长提示词。");
+  console.log("The full workflow is in xinyun-ai-init/README.md. No long prompt is needed.");
   console.log("");
 }
 
-main();
+main().catch((error) => {
+  console.error("[xinyun-ai-init] Unexpected error:", error && error.message ? error.message : error);
+  process.exit(1);
+});

package/init/xinyun-ai-init/README.md

@@ -31,6 +31,24 @@ AI 读取本文件后，必须按以下方式执行：
 7. 首次初始化不执行语言级语法检查、lint、typecheck、测试或构建命令；本机缺少运行时只记录为待确认，不展开长解释。
 8. 完成后用中文输出初始化或升级结果、项目导读、待确认问题和后续短指令。
 
+## 代码修改强制确认
+
+用户提出“帮我改”“修复”“处理一下”“优化一下”只代表提出需求，不代表授权执行。
+
+未确认前，只允许读取、分析、定位问题、输出方案；禁止 `apply_patch`、重写文件、格式化、自动修复、migration、seed、SQL、配置修改和任何会产生文件变化或业务副作用的命令。
+
+修改方案至少包含：
+
+1. 修改目标
+2. 影响范围
+3. 预计修改文件
+4. 是否影响数据库 / API / UI / 配置
+5. SQL 改动与执行提醒
+6. 验证方式
+7. 风险点
+
+只有用户明确回复“确认执行”“可以修改”“按方案改”“同意”等类似内容后，才允许在确认范围内执行。
+
 ## 欣芸技术开发 Agent 流
 
 这是一套面向 AI 编程工具的本地项目接手、按需理解、受控开发和持续沉淀方法论。
@@ -44,6 +62,22 @@ AI 读取本文件后，必须按以下方式执行：
 5. 受控整改：只在确认范围内修改，不顺手重构。
 6. 技术沉淀：会话结束前筛选有价值内容，沉淀到 `xinyun-ai/`；经验先候选，确认后升级。
 
+## 需求与 UI 理解
+
+涉及功能开发、业务流程、API、数据库、页面、组件、交互或样式时，AI 在输出修改方案前，必须先完成轻量需求理解。
+
+如果当前 AI 工具有需求分析、原型、UI 交互、截图风格识别等 Skill，优先调用对应 Skill；如果没有，则按 `rules/requirement-ui-understanding.md` 的清单兜底。
+
+信息不足时，只问 1-3 个关键问题，不展开长问卷。
+
+## 需求沉淀
+
+确认是开发需求时，后续可按需创建 `xinyun-ai/requirements/`，并使用 `REQ-YYYYMMDD-001` 格式编号。
+
+需求记录应包含原始需求、需求理解、涉及端、数据库 / API / UI / 配置影响、方案摘要、验收标准、实际改动文件、SQL 执行提醒和验证结果。
+
+普通聊天、工具使用咨询、无长期价值的临时排查、用户明确说不需要记录、与当前项目无关的内容，不沉淀。
+
 ## 执行模式
 
 如果项目没有 `xinyun-ai/`：
@@ -141,6 +175,18 @@ AI 可以沉淀项目经验，但不能自己升级正式规则。
 - 创建或修改 `xinyun-ai/` 内 Markdown 文件后，只做基础格式检查：标题、列表、代码块是否闭合。
 - 不运行项目业务 lint、build、test、typecheck。
 
+## 版本检测
+
+CLI 执行时会尽量检测当前包版本和 npm 线上最新版本。
+
+如果检测到本地版本低于线上版本，应提示用户使用：
+
+```md
+npx --yes @pm_zhousl/xinyun-ai-init@latest --force
+```
+
+版本检测失败不能阻塞初始化或升级流程。
+
 ## 输出要求
 
 初始化或升级完成后，输出：

package/init/xinyun-ai-init/rules/init-rules.md

@@ -4,4 +4,6 @@
 - 首次不创建大量规则、模板、脚本和业务沉淀目录。
 - 首次不执行语言级语法检查、lint、typecheck、测试或构建命令。
 - 每个端最多读取 3-5 个关键文件。
-- 不确定的信息标注：`推断`、`待确认`、`未在项目中发现`。
+- 不确定的信息标注：`推断`、`待确认`、`未在项目中发现`。
+- 首次初始化必须把“代码修改强制确认规则”写入 `AGENTS.md` 和 `xinyun-ai/rules/core-rules.md`。
+- 首次初始化只预留需求入口，不主动创建大量需求目录；后续确认是开发需求时再按需创建 `xinyun-ai/requirements/`。

package/init/xinyun-ai-init/rules/requirement-ui-understanding.md

@@ -0,0 +1,35 @@
+# 需求与 UI 理解规则
+
+开发类任务在输出修改方案前，必须先判断是否需要需求理解或 UI 理解。
+
+## Skill 适配
+
+如果当前 AI 工具有以下类型 Skill，应优先使用：
+
+- 需求理解类：`requirements-analyst`、PRD analyst、product requirements、user story、acceptance criteria
+- 原型流程类：`prototype-designer`、product flow、screen map、information architecture
+- UI 交互类：`ui-interaction-designer`、UI/UX designer、design reviewer
+- 截图风格类：`ui-screenshot-style-coder`、screenshot style、视觉还原
+- 全流程编排类：`product-build-orchestrator`、PRD to task、PRD to RFC
+
+如果没有对应 Skill，使用本规则内置清单兜底，不阻塞任务。
+
+## 需求理解清单
+
+1. 用户要解决的问题
+2. 预期结果
+3. 涉及端：server / admin / app / pc / 其他
+4. 涉及数据：数据库 / API / 配置 / 文件
+5. 验收标准
+6. 不明确点
+
+## UI 理解清单
+
+1. 页面位置
+2. 现有 UI 风格
+3. 用户操作路径
+4. 页面状态：默认 / 加载 / 空数据 / 错误 / 成功
+5. 是否影响移动端、多端适配或权限状态
+6. 是否需要参考截图、原型或现有页面
+
+信息不足时，只问 1-3 个关键问题。

package/init/xinyun-ai-init/rules/requirements-rules.md

@@ -0,0 +1,43 @@
+# 需求沉淀与任务追踪规则
+
+需求沉淀只服务于项目开发，不记录普通聊天、工具咨询、与当前项目无关的内容。
+
+## 触发场景
+
+- 新功能开发
+- 业务规则调整
+- 页面 / 交互 / 样式修改
+- API 行为变化
+- 数据库 / SQL 改动
+- 问题修复中产生可复用需求结论
+
+## 不沉淀场景
+
+- 普通聊天
+- 工具使用咨询
+- 临时排查但无长期项目价值
+- 用户明确说“不需要记录”
+- 与当前项目无关的内容
+
+## 编号与状态
+
+需求编号格式：
+
+```md
+REQ-YYYYMMDD-001
+```
+
+需求状态：
+
+- `draft`：草稿 / 待确认
+- `confirmed`：已确认
+- `planned`：已有方案
+- `in_progress`：执行中
+- `done`：已完成
+- `cancelled`：已取消
+
+## 记录要求
+
+需求记录至少包含：原始需求、需求理解、涉及端、数据库 / API / UI / 配置影响、待确认问题、方案摘要、验收标准、实际改动文件、SQL 执行提醒、验证结果和最后更新时间。
+
+运行到具体项目时，按需创建 `xinyun-ai/requirements/`，首次初始化不主动创建大量需求目录。

package/init/xinyun-ai-init/rules/upgrade-rules.md

@@ -12,4 +12,12 @@
 6. 不修改业务代码、配置、数据库、依赖、构建脚本、测试逻辑。
 7. 升级完成后按需写入 `xinyun-ai/upgrade-log.md`。
 
-涉及正式规则、目录结构、索引结构或历史沉淀迁移时，必须先确认。
+升级检查时必须重点检查：
+
+- `AGENTS.md` 是否包含代码修改强制确认规则。
+- `xinyun-ai/rules/core-rules.md` 是否包含代码修改强制确认规则。
+- 是否已有需求沉淀入口和 `current-task.md` 字段。
+- 是否需要补充需求与 UI 理解规则。
+- 当前 `xinyun-ai/manifest.json` 的版本是否低于初始化包版本。
+
+涉及正式规则、目录结构、索引结构或历史沉淀迁移时，必须先确认。

package/init/xinyun-ai-init/templates/AGENTS.template.md

@@ -2,6 +2,16 @@
 
 本项目使用 `xinyun-ai/` 管理 AI 协作规则。
 
+## 代码修改强制确认规则
+
+任何代码、配置、数据库、依赖、构建脚本、测试逻辑、API 行为、UI 行为或业务流程修改前，AI 必须先输出修改方案，并等待用户明确确认。
+
+用户提出“帮我改”“修复”“处理一下”“优化一下”只代表提出需求，不代表授权执行。
+
+未确认前，只允许读取、分析、定位问题、输出方案；禁止 `apply_patch`、重写文件、格式化、自动修复、migration、seed、SQL、配置修改和任何会产生文件变化或业务副作用的命令。
+
+只有用户明确回复“确认执行”“可以修改”“按方案改”“同意”等类似内容后，才允许在确认范围内执行。
+
 AI 接手本项目时，请先读取：
 
 - `xinyun-ai/README.md`

package/init/xinyun-ai-init/templates/README.template.md

@@ -7,6 +7,9 @@
 - 首次初始化为极速模式，后续能力按需补齐。
 - 后续 AI 会话优先读取 `manifest.json`、`current-task.md`、`rules/core-rules.md`、`index/project-index.json`。
 - 业务代码、配置、数据库、API、UI、业务流程修改前必须先出计划并等待确认。
+- 用户提出“帮我改”“修复”“处理一下”“优化一下”只代表提出需求，不代表授权执行。
+- 开发类任务在修改方案前应先完成需求理解；涉及页面、组件、交互或样式时应先完成 UI 理解。
+- 确认是开发需求时，可按需沉淀到 `requirements/`；普通聊天、工具咨询和无长期价值内容不沉淀。
 - 后续识别到新端、模块或能力时，只在 `xinyun-ai/` 内按需补齐对应目录和说明文件。
 
 ## 核心流程

package/init/xinyun-ai-init/templates/core-rules.template.md

@@ -4,6 +4,8 @@
 
 - 只读优先，禁止副作用命令。
 - 代码整改前必须先给修改方案，待用户确认后才能执行。
+- 用户提出“帮我改”“修复”“处理一下”“优化一下”只代表提出需求，不代表授权执行。
+- 未确认前，只允许读取、分析、定位问题、输出方案；禁止 `apply_patch`、重写文件、格式化、自动修复、migration、seed、SQL、配置修改和任何会产生文件变化或业务副作用的命令。
 - SQL / 数据库改动必须重点提醒。
 - 非项目内容不沉淀。
 - 多端项目按 `workstreams/<端名称>/` 分开说明。
@@ -13,6 +15,40 @@
 - 自我学习只沉淀候选经验，不自动改正式规则。
 - 目录自完善只补 `xinyun-ai/` 文档和索引，不修改业务代码。
 
+## 修改方案要求
+
+代码整改前的修改方案至少包含：
+
+1. 修改目标
+2. 影响范围
+3. 预计修改文件
+4. 是否影响数据库 / API / UI / 配置
+5. SQL 改动与执行提醒
+6. 验证方式
+7. 风险点
+
+## 需求与 UI 理解
+
+涉及功能、业务流程、API、数据库、页面、组件、交互或样式时，输出修改方案前必须先完成简版需求理解。
+
+如果当前 AI 工具有需求分析、原型、UI 交互、截图风格识别等 Skill，优先使用对应 Skill；没有 Skill 时，按内置清单兜底，不阻塞任务。
+
+需求理解至少确认：用户要解决的问题、预期结果、涉及端、涉及数据、验收标准和不明确点。
+
+UI 理解至少确认：页面位置、现有风格、用户操作路径、默认 / 加载 / 空数据 / 错误 / 成功状态、多端适配影响和是否需要参考截图。
+
+信息不足时，最多提出 1-3 个关键问题，不展开长问卷。
+
+## 需求沉淀
+
+确认是开发需求时，可按需创建 `xinyun-ai/requirements/` 并使用 `REQ-YYYYMMDD-001` 格式编号。
+
+需求状态建议：`draft`、`confirmed`、`planned`、`in_progress`、`done`、`cancelled`。
+
+需求记录应关联原始需求、需求理解、涉及端、数据库 / API / UI / 配置影响、方案摘要、验收标准、实际改动文件、SQL 提醒和验证结果。
+
+普通聊天、工具咨询、临时排查且无长期价值、用户明确说不需要记录、与当前项目无关的内容，不沉淀。
+
 ## 理解深度状态
 
 - `unknown`：未识别

package/init/xinyun-ai-init/templates/current-task.template.md

@@ -1,7 +1,14 @@
-# 当前任务
+# 当前任务
 
 - 状态：初始化
 - 用户原始需求：
+- 需求编号：
+- 需求理解：
 - 影响端：
+- 是否影响数据库 / API / UI / 配置：
+- 验收标准：
 - 待确认问题：
-- 本轮沉淀位置：
+- 修改方案摘要：
+- SQL 执行提醒：
+- 验证结果：
+- 本轮沉淀位置：

package/init/xinyun-ai-init/templates/manifest.template.json

@@ -1,7 +1,7 @@
 {
   "projectName": "",
-  "xinyunAiVersion": "1.0.0",
-  "scriptVersion": "2026.07.10",
+  "xinyunAiVersion": "1.1.0",
+  "scriptVersion": "2026.07.11",
   "schemaVersion": "1",
   "initializationMode": "fast",
   "expansionMode": "triggered",
@@ -10,8 +10,15 @@
     "overall": "quick",
     "workstreams": {},
     "database": "unknown",
-    "api": "unknown"
+    "api": "unknown",
+    "requirements": "unknown"
   },
   "codegraph": { "enabled": false, "status": "unknown" },
-  "index": { "primary": "json_markdown", "sqlite": "optional" }
-}
+  "index": { "primary": "json_markdown", "sqlite": "optional" },
+  "capabilities": {
+    "confirmationGate": true,
+    "requirementUnderstanding": true,
+    "uiUnderstanding": true,
+    "requirementTracking": true
+  }
+}

package/init/xinyun-ai-init/templates/project-index.template.json

@@ -4,10 +4,12 @@
     "overall": "quick",
     "workstreams": {},
     "database": "unknown",
-    "api": "unknown"
+    "api": "unknown",
+    "requirements": "unknown"
   },
   "database": "unknown",
   "api": "unknown",
+  "requirements": "unknown",
   "tests": "unknown",
   "lastUpdatedAt": ""
-}
+}

package/init/xinyun-ai-init/templates/requirement.template.md

@@ -0,0 +1,33 @@
+# 需求记录
+
+- 需求编号：REQ-YYYYMMDD-001
+- 状态：draft
+- 创建时间：
+- 最后更新时间：
+
+## 用户原始需求
+
+
+## 需求理解
+
+- 要解决的问题：
+- 预期结果：
+- 涉及端：
+- 涉及数据库 / API / UI / 配置：
+- 不明确点：
+
+## 验收标准
+
+1.
+
+## 修改方案摘要
+
+
+## 实际改动
+
+- 改动文件：
+- SQL 执行提醒：
+- 验证结果：
+
+## 备注
+

package/init/xinyun-ai-init/version.json

@@ -1,8 +1,8 @@
 {
   "packageName": "xinyun-ai-init",
   "displayName": "欣芸技术开发 Agent 流初始化包",
-  "version": "1.0.2",
-  "scriptVersion": "2026.07.10",
+  "version": "1.1.0",
+  "scriptVersion": "2026.07.11",
   "schemaVersion": "1",
   "defaultMode": "fast-init",
   "targetWorkspace": "xinyun-ai",

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@pm_zhousl/xinyun-ai-init",
-  "version": "1.0.2",
+  "version": "1.1.0",
   "description": "欣芸技术开发 Agent 流初始化包",
   "bin": {
     "xinyun-ai-init": "bin/xinyun-ai-init.js"