@finleywdx/ai-init 0.1.0

package/package.json

@@ -0,0 +1,52 @@
+{
+  "name": "@finleywdx/ai-init",
+  "version": "0.1.0",
+  "description": "AI 工程化工作流初始化器：一条命令把 spec-kit 工作流 + 记忆层 + 质量门禁铺进你的新项目。",
+  "keywords": [
+    "ai",
+    "spec-kit",
+    "spec-driven-development",
+    "scaffold",
+    "cli",
+    "workflow",
+    "quality-gate"
+  ],
+  "type": "module",
+  "bin": {
+    "ai-init": "dist/cli.js"
+  },
+  "files": [
+    "dist",
+    "templates",
+    "README.md",
+    "LICENSE"
+  ],
+  "engines": {
+    "node": ">=18"
+  },
+  "scripts": {
+    "build": "tsup",
+    "dev": "tsup --watch",
+    "clean": "rm -rf dist",
+    "prepublishOnly": "npm run clean && npm run build"
+  },
+  "dependencies": {
+    "commander": "^15.0.0",
+    "execa": "^9.6.1",
+    "picocolors": "^1.1.1"
+  },
+  "devDependencies": {
+    "@types/node": "^22.10.0",
+    "tsup": "^8.3.5",
+    "typescript": "^5.7.2"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "license": "MIT",
+  "author": "xfp",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/xufuping/Finley-main.git"
+  }
+}

package/templates/AGENTS.section.md

@@ -0,0 +1,41 @@
+<!-- FINLEY:START -->
+# Finley 工作流（AI 工程化）
+
+本项目由 [`@finleywdx/ai-init`](https://www.npmjs.com/package/@finleywdx/ai-init) 初始化，采用一套「spec-kit 规范驱动开发 + 质量门禁 + 跨会话记忆」的工作流。AI 助手在本项目工作时**必须遵循**下面的整体流程。
+
+## 整体流程
+
+1. **规范驱动开发（spec-kit）**：用 spec-kit 的斜杠命令按序推进，先想清楚「做什么/为什么」，再写代码：
+   - `/speckit.constitution` → 确立项目原则
+   - `/speckit.specify` → 写需求规格（不谈技术栈）
+   - `/speckit.clarify` → 澄清模糊点（plan 之前推荐）
+   - `/speckit.plan` → 定技术方案
+   - `/speckit.tasks` → 拆解可执行任务
+   - `/speckit.analyze` → 跨产物一致性检查（implement 之前推荐）
+   - `/speckit.implement` → 按任务实现
+   > Codex CLI 的 skills 模式用 `$speckit-*`；具体命令名以你的 agent 平台为准。
+
+2. **质量门禁（提交前强制）**：`/speckit.implement` 写完代码后、提交前，**必须**运行：
+   ```bash
+   python .finley/scripts/gate.py
+   ```
+   它跑 lint / typecheck / test；有红项必须**修复后重跑**，直至全绿才算实现完成。详见 skill `finley-quality-gate`。
+
+3. **收尾写 journal（记忆层）**：一段工作收尾时运行：
+   ```bash
+   python .finley/scripts/add_session.py --title "..." --summary "..." --commit "..."
+   ```
+   把本次进展写进 `.finley/workspace/<开发者>/`。**新会话开场**应主动读取该目录最近的 journal 恢复上下文。详见 skill `finley-memory`。
+
+## 关键位置
+
+- `.finley/config.yaml` — 质量门禁命令映射 + 开发者/journal 配置
+- `.finley/scripts/gate.py` — 质量门禁脚本
+- `.finley/scripts/add_session.py` — 记忆 journal 脚本
+- `.finley/workspace/` — 按开发者存放的跨会话记忆 journal
+- `.agents/skills/finley-quality-gate/` — 质量门禁 skill
+- `.agents/skills/finley-memory/` — 记忆层 skill
+- `.specify/` — spec-kit 自身的规格 / 模板 / 记忆（由 spec-kit 管理）
+
+> 本区块由 Finley 管理：位于 FINLEY 起止标记之间的内容可能被后续 `ai-init` 更新覆盖；标记之外的内容会被保留。
+<!-- FINLEY:END -->

package/templates/agents-skills/finley-memory/SKILL.md

@@ -0,0 +1,60 @@
+---
+name: finley-memory
+description: "跨会话记忆：一段工作收尾时运行 python .finley/scripts/add_session.py 把本次做了什么写进 journal；新会话开场主动读取 .finley/workspace/<开发者>/ 最近的 journal 以恢复上下文。用于结束一段实现工作、或刚开始新会话需要了解此前进展时。"
+---
+
+# Finley 记忆层
+
+Finley 的记忆层参考 Trellis 的做法：**把「本次会话发生了什么」持久化到仓库里的 journal**，让下一次会话（无论是你还是队友）不必从零理解项目。
+
+对话会被压缩，文件不会。经验、进展、坑，都落盘到 `.finley/workspace/<开发者>/`。
+
+---
+
+## 何时触发
+
+- **会话开场（读）**：新会话开始、需要了解此前进展时——主动读取最近的 journal 恢复上下文。
+- **工作收尾（写）**：完成一段实现 + 质量门禁通过后、准备结束这轮工作时——把这段会话写进 journal。
+
+---
+
+## 步骤 A：会话开场恢复上下文（读）
+
+1. 确认当前开发者目录：`.finley/workspace/<开发者>/`（开发者标识来自 git user.name / 环境变量 `FINLEY_DEVELOPER` / `.finley/config.yaml` 的 `developer`）。
+2. 先读该目录的 `index.md` 看「当前状态」和「会话历史」表，定位活跃的 journal 文件。
+3. 读最近的 `journal-N.md` 里最后 1~2 个 Session，了解上次做到哪、有什么待办和坑。
+4. 用这些上下文指导本次工作，避免重复劳动。
+
+```bash
+# 例：查看当前开发者的索引与最新 journal
+cat .finley/workspace/*/index.md
+```
+
+## 步骤 B：工作收尾写 journal（写）
+
+在一段工作（通常是一次 `/speckit.implement` + 门禁全绿）收尾时运行：
+
+```bash
+python .finley/scripts/add_session.py \
+  --title "本次工作的标题" \
+  --summary "一两句话总结做了什么、结论是什么" \
+  --commit "abc1234,def5678"
+```
+
+要点：
+
+- `--title` 必填；`--summary` 写清楚「做了什么 + 结果」。
+- `--commit` 填本次相关的 commit 哈希（逗号分隔）；纯规划性会话可省略。
+- 详细内容可用管道传入：`cat detail.md | python .finley/scripts/add_session.py --stdin --title "..."`。
+- 开发者/分支默认自动探测，必要时用 `--developer` / `--branch` 覆盖。
+
+脚本会把 Session 追加到 `journal-N.md`（超过 `journal.max_lines` 自动轮转到下一个），并更新 `index.md` 的会话历史表。
+
+---
+
+## 注意事项
+
+- **只做手动收尾摘要**：Finley 记忆层不做会话开场的自动上下文汇总——恢复上下文靠你按「步骤 A」主动读 journal。
+- **一段工作一条 Session**：不要把无关的多件事塞进一条；也不要每改一行就记一次。
+- **个人 journal 独立**：按开发者分目录存放，天然避免团队冲突；共享的规范/规格才进公共目录评审。
+- **与门禁配合**：推荐顺序是「实现 → `gate.py` 全绿 → `add_session.py` 收尾」。

package/templates/agents-skills/finley-quality-gate/SKILL.md

@@ -0,0 +1,62 @@
+---
+name: finley-quality-gate
+description: "强制质量门禁：在 /speckit.implement 写完代码后、提交前，必须运行 python .finley/scripts/gate.py 跑 lint/typecheck/test，红则修复再跑，直至全绿。用于任何写完或改完代码、准备结束一段实现工作或提交之前。"
+---
+
+# Finley 质量门禁
+
+这是 Finley 工作流里**不可跳过**的一道关卡。它保证「写完的代码在提交前一定跑过 lint / typecheck / test」。
+
+---
+
+## 何时触发
+
+只要满足以下任一情况，就必须执行本 skill：
+
+- 刚用 `/speckit.implement` 执行完一批任务、代码已落盘；
+- 手动改完任意源码、准备结束这段实现工作；
+- 准备 `git commit` / 发起提交之前。
+
+> 原则：**没跑过 `gate.py` 且全绿，就不算「实现完成」，更不允许提交。**
+
+---
+
+## 步骤
+
+### 1. 运行门禁
+
+在项目根目录执行：
+
+```bash
+python .finley/scripts/gate.py
+```
+
+它会：
+
+1. 读取 `.finley/config.yaml` 的 `quality.frontend` / `quality.backend` 命令；
+2. 对占位命令自动探测（前端读 `package.json` 的 scripts，后端读 `pyproject.toml`）；
+3. 逐条运行 lint / typecheck / test，并在末尾聚合「通过 / 失败」清单。
+
+### 2. 判读结果
+
+- **全绿**（退出码 0）：门禁通过，可以继续收尾 / 提交。
+- **有红项**（退出码 1）：按输出里列出的失败项定位问题。
+- **未解析到命令**（退出码 2）：说明门禁尚未配置——去 `.finley/config.yaml` 填入真实命令，或确认 `package.json` / `pyproject.toml` 里有可被探测的脚本，然后重跑。**不要因为"没有命令"就当作通过。**
+
+### 3. 修复后重跑
+
+若有失败：**先修复代码，再重新运行 `gate.py`**，如此循环，直到全部通过为止。不要用注释、跳过测试、放宽类型等方式绕过门禁。
+
+### 4. 记录（可选）
+
+门禁通过后，若这段工作到此收尾，按 `finley-memory` skill 运行 `add_session.py` 写 journal。
+
+---
+
+## 注意事项
+
+- **只增不减**：不要为了让门禁变绿而删除/禁用已有的 lint 规则、类型检查或测试。
+- **占位不等于通过**：`.finley/config.yaml` 里形如 `<占位: ...>` 的命令会触发自动探测；探测不到时门禁会以退出码 2 失败，提醒你去配置。
+- **前后端分离**：只想跑一侧时用 `--only frontend` 或 `--only backend`；但**提交前应跑全部**。
+- **想先看会跑什么**：用 `python .finley/scripts/gate.py --dry-run` 预览命令而不执行。
+- 门禁失败时进程会非零退出，CI / 提交前钩子可据此阻断。

package/templates/finley/config.yaml

@@ -0,0 +1,51 @@
+# Finley 配置文件
+# ---------------------------------------------------------------------------
+# 这是 @finleywdx/ai-init 铺进项目的「增量层」配置。
+# 它只负责两件事：质量门禁命令映射（gate.py 读）、记忆 journal 设置（add_session.py 读）。
+# spec-kit 自身的配置在 .specify/ 目录，与本文件互不干扰。
+
+# ---------------------------------------------------------------------------
+# quality —— 质量门禁命令映射
+# ---------------------------------------------------------------------------
+# gate.py 会按下面的命令逐条执行；任一失败则整体门禁失败（非零退出）。
+#
+# 占位说明：值形如 "<占位: ...>" 表示尚未配置。gate.py 遇到占位会尝试
+# 自动探测：
+#   - 前端（frontend）从目标项目的 package.json 的 scripts 里找
+#     lint / typecheck(或 type-check) / test。
+#   - 后端（backend）从 pyproject.toml 里探测工具链：
+#     检测到 ruff  -> `ruff check .`
+#     检测到 mypy  -> `mypy .`
+#     检测到 pytest -> `pytest`
+#
+# 你可以随时把占位替换成项目里真实的命令，例如：
+#   frontend:
+#     lint: "npm run lint"
+#     typecheck: "npm run typecheck"
+#     test: "npm test"
+quality:
+  # 前端 / Node 侧命令
+  frontend:
+    lint: "<占位: 前端 lint 命令，如 npm run lint>"
+    typecheck: "<占位: 前端类型检查命令，如 npm run typecheck>"
+    test: "<占位: 前端测试命令，如 npm test>"
+  # 后端 / Python 侧命令
+  backend:
+    lint: "<占位: 后端 lint 命令，如 ruff check .>"
+    typecheck: "<占位: 后端类型检查命令，如 mypy .>"
+    test: "<占位: 后端测试命令，如 pytest>"
+
+# ---------------------------------------------------------------------------
+# developer —— 开发者标识
+# ---------------------------------------------------------------------------
+# journal 会写到 .finley/workspace/<developer>/ 下。
+# 留空时 add_session.py 自动探测：
+#   环境变量 FINLEY_DEVELOPER > git config user.name > 系统用户名
+developer: ""
+
+# ---------------------------------------------------------------------------
+# journal —— 记忆层设置
+# ---------------------------------------------------------------------------
+journal:
+  # 单个 journal 文件超过该行数后，自动轮转到下一个 journal-N.md
+  max_lines: 2000

package/templates/finley/scripts/add_session.py

@@ -0,0 +1,280 @@
+#!/usr/bin/env python3
+# -*- coding: utf-8 -*-
+"""Finley 记忆层 —— 在一段工作收尾时把「本次会话做了什么」写进 journal。
+
+用法：
+    python .finley/scripts/add_session.py --title "标题" --summary "一句话总结"
+    python .finley/scripts/add_session.py --title "标题" --commit "abc123,def456" --summary "..."
+    python .finley/scripts/add_session.py --title "标题" --developer alice   # 指定开发者
+    cat detail.md | python .finley/scripts/add_session.py --title "标题" --stdin
+
+journal 写到 .finley/workspace/<开发者>/journal-N.md：
+    - 开发者标识解析顺序：--developer > 环境变量 FINLEY_DEVELOPER
+      > config.yaml 的 developer > git config user.name > 系统用户名。
+    - 单个 journal 超过 config.yaml 的 journal.max_lines（默认 2000）行后，
+      自动轮转到下一个 journal-(N+1).md。
+    - 同时维护该开发者目录下的 index.md（会话总数 / 活跃文件 / 历史表）。
+
+纯标准库实现（os / re / subprocess / argparse），不依赖任何第三方包。
+"""
+
+from __future__ import annotations
+
+import argparse
+import os
+import re
+import subprocess
+import sys
+from datetime import datetime
+from pathlib import Path
+
+JOURNAL_PREFIX = "journal-"
+DEFAULT_MAX_LINES = 2000
+
+
+# =============================================================================
+# 配置读取（复用极简 YAML 思路，仅取需要的两个字段）
+# =============================================================================
+
+def _read_config(repo_root: Path) -> dict:
+    path = repo_root / ".finley" / "config.yaml"
+    result = {"developer": "", "max_lines": DEFAULT_MAX_LINES}
+    if not path.exists():
+        return result
+
+    in_journal = False
+    for raw in path.read_text(encoding="utf-8").splitlines():
+        line = raw.split("#", 1)[0].rstrip()
+        if not line.strip():
+            continue
+        indent = len(line) - len(line.lstrip(" "))
+        stripped = line.strip()
+
+        if indent == 0:
+            in_journal = stripped.startswith("journal:")
+            if stripped.startswith("developer:"):
+                val = stripped.split(":", 1)[1].strip().strip("'\"")
+                if val:
+                    result["developer"] = val
+        elif in_journal and "max_lines" in stripped:
+            m = re.search(r"(\d+)", stripped)
+            if m:
+                result["max_lines"] = int(m.group(1))
+    return result
+
+
+# =============================================================================
+# 开发者与仓库定位
+# =============================================================================
+
+def get_repo_root() -> Path:
+    return Path(__file__).resolve().parent.parent.parent  # .finley/scripts/ -> root
+
+
+def _git(args: list[str], cwd: Path) -> str:
+    try:
+        out = subprocess.run(
+            ["git", *args], cwd=str(cwd), capture_output=True, text=True, check=False
+        )
+        return out.stdout.strip()
+    except (OSError, subprocess.SubprocessError):
+        return ""
+
+
+def resolve_developer(repo_root: Path, cli_value: str | None, config: dict) -> str:
+    for candidate in (
+        cli_value,
+        os.environ.get("FINLEY_DEVELOPER"),
+        config.get("developer"),
+        _git(["config", "user.name"], repo_root),
+        os.environ.get("USER") or os.environ.get("USERNAME"),
+    ):
+        if candidate and str(candidate).strip():
+            # 规范化成适合作目录名的标识
+            return re.sub(r"[^\w.\-]+", "-", str(candidate).strip())
+    return "unknown"
+
+
+def resolve_branch(repo_root: Path, cli_value: str | None) -> str | None:
+    if cli_value:
+        return cli_value
+    branch = _git(["branch", "--show-current"], repo_root)
+    return branch or None
+
+
+# =============================================================================
+# journal 文件管理
+# =============================================================================
+
+def get_latest_journal(dev_dir: Path) -> tuple[Path | None, int, int]:
+    """返回 (最新 journal 路径, 编号, 行数)。目录为空时返回 (None, 0, 0)。"""
+    latest_file: Path | None = None
+    latest_num = -1
+    for f in dev_dir.glob(f"{JOURNAL_PREFIX}*.md"):
+        if not f.is_file():
+            continue
+        m = re.search(r"(\d+)$", f.stem)
+        if m and int(m.group(1)) > latest_num:
+            latest_num = int(m.group(1))
+            latest_file = f
+    if latest_file:
+        lines = len(latest_file.read_text(encoding="utf-8").splitlines())
+        return latest_file, latest_num, lines
+    return None, 0, 0
+
+
+def create_journal_file(dev_dir: Path, num: int, developer: str, today: str, max_lines: int) -> Path:
+    new_file = dev_dir / f"{JOURNAL_PREFIX}{num}.md"
+    if num <= 1:
+        cont_line = f"> 单文件约 {max_lines} 行后自动轮转到下一个 journal\n"
+    else:
+        cont_line = f"> 续自 `{JOURNAL_PREFIX}{num - 1}.md`（约 {max_lines} 行后轮转）\n"
+    header = (
+        f"# Journal - {developer} (Part {num})\n\n"
+        f"{cont_line}"
+        f"> 起始：{today}\n\n---\n"
+    )
+    new_file.write_text(header, encoding="utf-8")
+    return new_file
+
+
+def get_session_count(index_file: Path) -> int:
+    if not index_file.is_file():
+        return 0
+    for line in index_file.read_text(encoding="utf-8").splitlines():
+        if "会话总数" in line or "Total Sessions" in line:
+            m = re.search(r"[:：]\s*(\d+)", line)
+            if m:
+                return int(m.group(1))
+    return 0
+
+
+def build_session_block(
+    session_num: int, title: str, today: str, task: str, summary: str,
+    detail: str, commit: str, branch: str | None,
+) -> str:
+    if commit and commit != "-":
+        rows = "\n".join(
+            f"| `{c.strip()}` | (见 git log) |" for c in commit.split(",") if c.strip()
+        )
+        commit_table = "| Hash | 说明 |\n|------|------|\n" + rows
+    else:
+        commit_table = "（无提交 / 规划性会话）"
+
+    branch_line = f"\n**Branch**: `{branch}`" if branch else ""
+
+    return (
+        f"\n\n## Session {session_num}: {title}\n\n"
+        f"**日期**: {today}\n"
+        f"**Task**: {task}{branch_line}\n\n"
+        f"### Summary\n\n{summary}\n\n"
+        f"### 主要改动\n\n{detail}\n\n"
+        f"### Git Commits\n\n{commit_table}\n\n"
+        f"### 状态\n\n✅ 已完成\n"
+    )
+
+
+def write_index(index_file: Path, active_file: str, session_num: int, today: str,
+                title: str, commit: str, branch: str | None, developer: str) -> None:
+    commit_disp = "-"
+    if commit and commit != "-":
+        commit_disp = re.sub(r"([0-9a-f]{7,})", r"`\1`", commit.replace(",", ", "))
+    branch_disp = f"`{branch}`" if branch else "-"
+
+    header = (
+        f"# Journal 索引 - {developer}\n\n"
+        f"## 当前状态\n\n"
+        f"- **活跃文件**: `{active_file}`\n"
+        f"- **会话总数**: {session_num}\n"
+        f"- **最近活跃**: {today}\n\n"
+        f"## 会话历史\n\n"
+        f"| # | 日期 | 标题 | Commits | Branch |\n"
+        f"|---|------|------|---------|--------|\n"
+    )
+
+    existing_rows: list[str] = []
+    if index_file.is_file():
+        capture = False
+        for line in index_file.read_text(encoding="utf-8").splitlines():
+            if line.startswith("|---") or re.match(r"^\|\s*#\s*\|", line):
+                capture = True
+                continue
+            if capture and line.startswith("|"):
+                existing_rows.append(line)
+
+    new_row = f"| {session_num} | {today} | {title} | {commit_disp} | {branch_disp} |"
+    body = "\n".join([new_row, *existing_rows])
+    index_file.write_text(header + body + "\n", encoding="utf-8")
+
+
+# =============================================================================
+# 主流程
+# =============================================================================
+
+def main() -> int:
+    parser = argparse.ArgumentParser(description="Finley：把本次会话写进 journal")
+    parser.add_argument("--title", required=True, help="会话标题")
+    parser.add_argument("--task", help="任务名（默认取 --title）")
+    parser.add_argument("--summary", default="（补充总结）", help="一句话总结")
+    parser.add_argument("--commit", default="-", help="逗号分隔的 commit 哈希")
+    parser.add_argument("--content-file", help="从文件读取详细内容")
+    parser.add_argument("--stdin", action="store_true", help="从标准输入读取详细内容")
+    parser.add_argument("--developer", help="开发者标识（默认自动探测）")
+    parser.add_argument("--branch", help="分支名（默认自动探测）")
+    args = parser.parse_args()
+
+    repo_root = get_repo_root()
+    config = _read_config(repo_root)
+    max_lines = int(config.get("max_lines", DEFAULT_MAX_LINES))
+
+    developer = resolve_developer(repo_root, args.developer, config)
+    branch = resolve_branch(repo_root, args.branch)
+
+    workspace = repo_root / ".finley" / "workspace"
+    dev_dir = workspace / developer
+    dev_dir.mkdir(parents=True, exist_ok=True)
+
+    detail = "（补充细节）"
+    if args.content_file and Path(args.content_file).is_file():
+        detail = Path(args.content_file).read_text(encoding="utf-8")
+    elif args.stdin:
+        detail = sys.stdin.read()
+
+    today = datetime.now().strftime("%Y-%m-%d")
+    index_file = dev_dir / "index.md"
+    session_num = get_session_count(index_file) + 1
+
+    block = build_session_block(
+        session_num, args.title, today, args.task or args.title,
+        args.summary, detail, args.commit, branch,
+    )
+
+    journal_file, current_num, current_lines = get_latest_journal(dev_dir)
+    block_lines = len(block.splitlines())
+
+    if journal_file is None:
+        current_num = 1
+        journal_file = create_journal_file(dev_dir, 1, developer, today, max_lines)
+    elif current_lines + block_lines > max_lines:
+        current_num += 1
+        print(
+            f"[Finley] 当前 journal 超过 {max_lines} 行，轮转到 "
+            f"{JOURNAL_PREFIX}{current_num}.md",
+            file=sys.stderr,
+        )
+        journal_file = create_journal_file(dev_dir, current_num, developer, today, max_lines)
+
+    with journal_file.open("a", encoding="utf-8") as f:
+        f.write(block)
+
+    active_file = f"{JOURNAL_PREFIX}{current_num}.md"
+    write_index(index_file, active_file, session_num, today, args.title,
+                args.commit, branch, developer)
+
+    print(f"[Finley] ✅ 已记录 Session {session_num} 到 {dev_dir}/{active_file}")
+    print(f"         开发者：{developer}  分支：{branch or '-'}")
+    return 0
+
+
+if __name__ == "__main__":
+    sys.exit(main())