Claude Skill

init-project

当用户明确要求"初始化项目"、"创建项目指令文件"或"生成 AGENTS.md"时使用。完全自动化:自动检测操作系统默认语言,分析项目目录结构(支持 Python/Web/Rust/Go/Java/数据科学/文档项目等),推断项目类型和用途,一键生成规范的项目指令文档。生成结果包括:AGENTS.md(跨平台通用项目指令,Single Source of Truth)、CLAUDE.md(Claude Code 特定适配,通过 @./AGENTS.md 引用)、README.md(项目介绍与使用方法)、CHANGELOG.md(项目变更记录)、.giti

LLM Mart · 0 points · 21 views 38 listing impressions 0 install-command copies

#claude-code

Download huangwb8-skills-skills_alpha_init-project-7680481.zip · 41 KB

Install

skills CLI npx skills add https://github.com/huangwb8/skills/tree/main/skills/alpha/init-project
Claude Code claude plugin marketplace add https://llmmart.ai/marketplace.json && claude plugin install huangwb8-skills@llmmart
Git git clone https://github.com/huangwb8/skills.git

The skills CLI installs just this skill, for any of its supported agents. Claude Code installs the whole huangwb8/skills collection as a plugin from our marketplace. Git is the plain clone.

README

Init Project

这个 skill 用来为当前项目初始化标准化的 AI 协作文档和基础仓库文件,适合新项目起步或已有项目补齐指令体系;它只应该在当前项目目录内工作,不应越界修改其它目录。

用法

最推荐用法

请使用 init-project skill 为本项目进行初始化。
输入:当前项目根目录
输出:`AGENTS.md`、`CLAUDE.md`、`README.md`、`CHANGELOG.md`、`.gitignore`、`docs/`、`docs/plans/`

进阶用法

请使用 init-project skill 为本项目进行初始化。
输入:当前项目根目录
输出:标准化项目指令与说明文档
另外,还有下列参数约束:
- 尽量保留已有内容
- 默认语言自动检测
- 不修改当前目录之外的文件

能做什么

  • 为项目生成 AGENTS.md、CLAUDE.md、README.md、CHANGELOG.md、.gitignore,并初始化 docs/ 与 docs/plans/。
  • 不默认创建项目根目录 skills/;已有目录与内容会保留。
  • 把 AGENTS.md 作为跨平台通用指令的单一真相来源。
  • 让 CLAUDE.md 成为面向 Claude Code 的轻量适配层。
  • 自动分析项目结构、项目类型和默认语言。
  • 兼容 Windows GBK 等非 UTF-8 控制台;状态符号无法显示时会安全转义,不会把真实业务失败误报为成功。
  • 默认启用 BAC 贡献记录:检查 Python 环境和 bac 包,必要时安装,并初始化 docs/contribution.bac。
  • 不适合拿来扫描父目录、批量改多个项目,或无边界地覆盖已有文件。

使用示例

示例 1:初始化一个新项目

请使用 init-project skill 为本项目进行初始化。
输入:当前项目根目录
输出:完整的项目指令文件与说明文档

示例 2:为已有项目补齐协作文档

请使用 init-project skill 初始化这个已有仓库。
输入:当前项目根目录
输出:`AGENTS.md`、`CLAUDE.md`、`README.md`、`CHANGELOG.md`、`.gitignore`、`docs/`、`docs/plans/`
另外,还有下列参数约束:
- 尽量保留已有 README 的有效信息
- 不破坏现有项目结构

示例 3:只补某一类文档

请使用 init-project skill 为本项目补齐说明文档。
输入:当前项目根目录
输出:README 或 CHANGELOG
另外,还有下列参数约束:
- 只更新 README

输出

  • AGENTS.md:跨平台通用项目指令,应该被长期维护。
  • CLAUDE.md:Claude Code 适配层,核心内容应与 AGENTS.md 保持一致。
  • README.md:项目介绍、快速开始和目录说明。
  • CHANGELOG.md:项目变更记录。
  • .gitignore:默认的安全与项目类型忽略规则。
  • docs/:项目文档根目录。
  • docs/plans/:计划文档固定目录;其余 docs/ 文档在代码变化时也应及时同步更新。
  • docs/contribution.bac:默认 BAC 贡献托管文件;用户可通过 --bac-file 指定其它项目内路径。

配置

  • 配置文件:init-project/config.yaml
  • 关键配置节:
    • language_mapping
    • bac_contribution
    • agents_required_sections
    • claude_required_sections
    • readme_required_sections
    • changelog_required_sections
  • 这个 skill 的默认定位是“完整初始化”,不是只生成一份孤立文档。

备选用法(脚本/硬编码)

如果你想直接在命令行下执行项目初始化,脚本入口最方便。

自动分析当前目录并生成文件

python3 init-project/scripts/generate.py --auto

自动分析并覆盖已有文件

python3 init-project/scripts/generate.py --auto --overwrite

只生成部分文档

python3 init-project/scripts/generate.py --auto --only-readme
python3 init-project/scripts/generate.py --auto --only-changelog

跳过部分输出

python3 init-project/scripts/generate.py \
  --auto \
  --skip-readme \
  --skip-changelog \
  --skip-gitignore

BAC 贡献记录

# 默认开启:检查/安装 bac,并初始化 docs/contribution.bac
python3 init-project/scripts/generate.py --auto

# 指定项目内的其它 BAC 文件
python3 init-project/scripts/generate.py --auto --bac-file docs/audit/contribution.bac

# 随时显式关闭 BAC 初始化步骤
python3 init-project/scripts/generate.py --auto --disable-bac

关闭后,生成的 AGENTS.md 会明确 BAC 当前未启用,不再保留“默认且强制”的启用态指令。

BAC 基于 https://github.com/huangwb8/bensz-auto-contribution,用于客观记录人类与 AI 的协作过程和证据,不替代最终署名、责任或合规判断。

常见问题

Q:AGENTS.md 和 CLAUDE.md 到底谁是主文件?

A:AGENTS.md 是单一真相来源;CLAUDE.md 是平台适配层。维护时应优先保证 AGENTS.md 的口径正确。

Q:它会不会改到当前项目目录之外?

A:不应该。这个 skill 的边界就是“当前目录内生成或更新项目文件”。

Q:既然是自动化,是不是可以放心覆盖任何已有文件?

A:不能这么理解。自动化不等于无脑覆盖。是否覆盖应由你显式决定,例如使用 --overwrite。

Q:为什么 .gitignore 也算初始化结果的一部分?

A:因为它直接关系到项目安全和仓库整洁度,尤其能防止敏感文件、系统文件和缓存文件被误提交。

Skill manifest

Init Project

目标

当用户明确要求初始化项目、创建项目指令文件、生成 AGENTS.md,或为已有项目补齐 AI 协作规范时使用。本 Skill 分析项目结构,并生成或更新适用于当前项目的标准化协作文档与基础目录。

流程

输入

输入为目标项目根目录及用户选择的初始化模式;可选输入包括项目名称/描述、工作流、输出开关、--overwrite、--bac-file 和 --disable-bac。输出路径必须位于当前项目目录内,现有治理文件和用户自定义章节应先识别再合并。

执行步骤

目标与边界

为当前项目生成标准 AI 协作文档,让 Claude Code / OpenAI Codex CLI 等工具理解项目目标、工程原则、变更记录规则与协作边界。

只允许在当前工作目录及其子目录内创建或修改文件。禁止写入父目录、其它项目、系统目录或用户级配置。脚本会在写入前校验输出路径,失败时立即停止。

核心约束

  • AGENTS.md 是唯一需要长期手动维护的通用指令源;CLAUDE.md 只做 Claude Code 适配,并通过 @./AGENTS.md 自动引用。
  • 生成模板统一放在 init-project/templates/:AGENTS.md.template、CLAUDE.md.template、README.md.template、CHANGELOG.md.template、gitignore.yaml。
  • 配置统一放在 init-project/config.yaml,版本号以 skill_info.version 为准;当前 BAC 配置在 bac_contribution。
  • 完整初始化必须补齐 docs/ 与 docs/plans/;不默认创建项目根目录 skills/,保留项目已有的目录与内容。
  • 代码变化导致 docs/ 中非 plans/ 文档过时时,生成的项目指令必须要求同步更新。
  • 影响项目行为、结构、工作流、工程原则、指令文件或关键配置的变更,必须写入 CHANGELOG.md 的 [Unreleased]。

BAC 贡献记录

默认基于 bensz-auto-contribution / bac 记录人类、AI 与工具贡献证据:

  • 默认仓库:https://github.com/huangwb8/bensz-auto-contribution
  • 默认安装源:git+https://github.com/huangwb8/bensz-auto-contribution.git
  • 默认文件:docs/contribution.bac
  • Python 要求:config.yaml:bac_contribution.min_python_version,当前为 3.10
  • 默认开启;用户可随时通过 --disable-bac 显式关闭。关闭时生成的文档也必须说明当前已关闭且可重新启用。
  • 用户通过 --bac-file 指定项目内其它路径时,以用户指定为准;禁止把 .bac 文件写到项目目录外。

BAC 是过程记录与辅助审计材料,不替代最终署名、责任或合规判断;不得记录敏感密钥、完整私有提示词或无关个人隐私。

推荐执行

在目标项目根目录运行:

python3 init-project/scripts/generate.py --auto

常用参数:

# 覆盖/强制更新已有文件
python3 init-project/scripts/generate.py --auto --overwrite

# 指定 BAC 文件,必须位于项目目录内
python3 init-project/scripts/generate.py --auto --bac-file docs/audit/contribution.bac

# 显式关闭默认 BAC 初始化
python3 init-project/scripts/generate.py --auto --disable-bac

# 只生成单类文档 / 跳过可选输出
python3 init-project/scripts/generate.py --auto --only-readme
python3 init-project/scripts/generate.py --auto --only-changelog
python3 init-project/scripts/generate.py --auto --skip-readme --skip-gitignore

手动模式只在用户明确给出项目信息时使用:

python3 init-project/scripts/generate.py \
  --project-name "my-project" \
  --project-description "数据科学项目" \
  --workflow "数据获取 → 分析 → 可视化"

自动模式流程

--auto 会依次完成:

  1. 验证输出目录必须位于当前工作目录内。
  2. 分析项目:从 README 提取名称/描述,按标志文件识别项目类型,生成最多 2 层目录树。
  3. 检测默认语言,失败时回退到简体中文。
  4. 完整初始化时创建 docs/ 与 docs/plans/。
  5. 按配置决定是否启用 BAC:检查 Python 与 bac 包,必要时安装,初始化或验证 .bac 文件。
  6. 生成或智能合并 AGENTS.md、CLAUDE.md。
  7. 按条件生成 README.md、CHANGELOG.md、.gitignore。
  8. 输出生成文件、目录与项目分析摘要。

项目类型识别标志:Python(pyproject.toml、requirements.txt 等)、Web(package.json 等)、Rust(Cargo.toml)、Go(go.mod)、Java(pom.xml/Gradle)、数据科学(*.ipynb、*.R、environment.yml)、文档(docs/、mkdocs.yml、docusaurus.config.js)。

智能合并策略

当 AGENTS.md 或 CLAUDE.md 已存在时,默认智能合并而非直接覆盖:保留用户自定义的 ## 项目目标、## 核心工作流、## 变更边界 及非标准章节;更新工程原则、默认语言、平台适配、AGENTS.md 必需章节与 CLAUDE.md 的 @./AGENTS.md 引用。AGENTS.md 中历史遗留的 ## 目录结构 会被丢弃,避免回填为自定义章节;合并不符合预期时提示用户用 --overwrite。

.gitignore 策略

从 templates/gitignore.yaml 读取规则;缺少 PyYAML 或配置损坏时使用默认规则兜底。安全优先,默认忽略系统文件、IDE 配置、日志、临时文件、环境变量、密钥、凭证目录和常见构建/缓存产物。已有 .gitignore 在覆盖模式下会保留用户自定义规则。

输出

输出文件

  • AGENTS.md:跨平台通用项目指令,Single Source of Truth;必生成,智能合并。
  • CLAUDE.md:Claude Code 适配层,核心为 @./AGENTS.md;必生成,智能合并。
  • README.md、CHANGELOG.md、.gitignore:按需生成;--overwrite 可覆盖/合并。项目变更必须维护 CHANGELOG.md。
  • docs/、docs/plans/:完整初始化时自动补齐;计划文档固定放在 ./docs/plans/。
  • docs/contribution.bac:默认 BAC 账本;--bac-file 可改,--disable-bac 可关。

输出管理

BenszAPI 任务工作区

校验

交付前检查

  • AGENTS.md 包含必需章节:项目目标、核心工作流、工程原则、默认语言、联网与搜索、贡献记录、Codex CLI 特定说明、变更记录与版本、有机更新原则。
  • CLAUDE.md 正确通过 @./AGENTS.md 引用通用指令。
  • docs/、docs/plans/ 已存在或无需本模式创建;未默认创建项目根目录 skills/。
  • BAC 已初始化/验证,或用户已显式使用 --disable-bac。
  • .gitignore 已生成/合并,且包含敏感文件忽略规则。
  • CHANGELOG.md 已创建或变更已记录。
  • 未写入当前项目目录之外的文件。

失败与恢复

错误处理

  • Windows GBK 等非 UTF-8 控制台不会因装饰性 Unicode 状态符号中止;脚本保留宿主编码,仅转义无法编码的字符,业务异常与退出码仍按原逻辑传播。
  • 输出目录越界、目标目录不存在或不是目录:停止。
  • docs / docs/plans 已存在但不是目录:停止。
  • BAC 安装、导入、初始化或验证失败:停止,并提示可用 --disable-bac 显式关闭。
  • 语言检测失败:回退到简体中文。
  • 项目类型无法识别:使用通用项目模板。
  • PyYAML 缺失:脚本继续运行,配置与 .gitignore 使用默认值。

约束

公共硬约束

本块由 docs/templates/skill-common-constraints.md 统一维护;每个 SKILL.md 的 ## 约束 必须逐字同步本块,不得在副本中改写公共规则。

  • 任务需要落盘时,使用唯一的 ./.bensz-api/task-{yyyymmdd-hhmm}-{简短描述}/ 根目录;共享材料放入 shared/,Skill 专属材料放入该 Skill 的 input/、output/、log/。
  • 正式交付物、源代码和正式计划按项目约定保存,不写入任务工作区;未经授权不覆盖、删除、迁移或远程写入。
  • 项目维护变更检查 BAC 可用性并记录需求、AI 产出、工具结果、文件改动和验证摘要;BAC 只做过程审计,不替代署名、责任或合规判断。
  • 不记录 API Key、访问令牌、密码、Cookie、环境/凭据文件、私有 Prompt、身份信息、本地用户名、主机名或不必要的大体积原始数据。
  • 文件路径必须规范化并限制在授权项目范围内;外部 URL、子进程和网络访问遵循最小权限,防止路径遍历、SSRF 和命令注入。
  • Skill 版本唯一记录在自身 config.yaml:skill_info.version;公开 API、协议、目录或配置变更同步文档与 CHANGELOG.md。
  • bensz-collect-bugs 是一个 Agent Skill;仅将 Bensz Agent Skill 或 Bensz 基础设施本身的设计缺陷交给它。先脱敏写入 ~/.bensz-skills/bugs/,当前任务不中断,只有用户明确要求才公开上报,禁止直接修改用户已安装的 Skill 源码。
Files (skills)
  • scripts
    • generate.py 64.9 KB
      Loading…
    • test_console_encoding.py 6.7 KB
      Loading…
  • templates
    • AGENTS.md.template 4.8 KB · in bundle
    • CHANGELOG.md.template 986 B · in bundle
    • CLAUDE.md.template 411 B · in bundle
    • gitignore.yaml 5.1 KB
      Loading…
    • README.md.template 1.2 KB · in bundle
  • CHANGELOG.md 13.3 KB
    Loading…
  • config.yaml 4 KB
    Loading…
  • README.md 5.3 KB
    # Init Project
    
    这个 skill 用来为当前项目初始化标准化的 AI 协作文档和基础仓库文件,适合新项目起步或已有项目补齐指令体系;它只应该在当前项目目录内工作,不应越界修改其它目录。
    
    ## 用法
    
    ### 最推荐用法
    
    ```text
    请使用 init-project skill 为本项目进行初始化。
    输入:当前项目根目录
    输出:`AGENTS.md`、`CLAUDE.md`、`README.md`、`CHANGELOG.md`、`.gitignore`、`docs/`、`docs/plans/`
    ```
    
    ### 进阶用法
    
    ```text
    请使用 init-project skill 为本项目进行初始化。
    输入:当前项目根目录
    输出:标准化项目指令与说明文档
    另外,还有下列参数约束:
    - 尽量保留已有内容
    - 默认语言自动检测
    - 不修改当前目录之外的文件
    ```
    
    ## 能做什么
    
    - 为项目生成 `AGENTS.md`、`CLAUDE.md`、`README.md`、`CHANGELOG.md`、`.gitignore`,并初始化 `docs/` 与 `docs/plans/`。
    - 不默认创建项目根目录 `skills/`;已有目录与内容会保留。
    - 把 `AGENTS.md` 作为跨平台通用指令的单一真相来源。
    - 让 `CLAUDE.md` 成为面向 Claude Code 的轻量适配层。
    - 自动分析项目结构、项目类型和默认语言。
    - 兼容 Windows GBK 等非 UTF-8 控制台;状态符号无法显示时会安全转义,不会把真实业务失败误报为成功。
    - 默认启用 BAC 贡献记录:检查 Python 环境和 `bac` 包,必要时安装,并初始化 `docs/contribution.bac`。
    - 不适合拿来扫描父目录、批量改多个项目,或无边界地覆盖已有文件。
    
    ## 使用示例
    
    ### 示例 1:初始化一个新项目
    
    ```text
    请使用 init-project skill 为本项目进行初始化。
    输入:当前项目根目录
    输出:完整的项目指令文件与说明文档
    ```
    
    ### 示例 2:为已有项目补齐协作文档
    
    ```text
    请使用 init-project skill 初始化这个已有仓库。
    输入:当前项目根目录
    输出:`AGENTS.md`、`CLAUDE.md`、`README.md`、`CHANGELOG.md`、`.gitignore`、`docs/`、`docs/plans/`
    另外,还有下列参数约束:
    - 尽量保留已有 README 的有效信息
    - 不破坏现有项目结构
    ```
    
    ### 示例 3:只补某一类文档
    
    ```text
    请使用 init-project skill 为本项目补齐说明文档。
    输入:当前项目根目录
    输出:README 或 CHANGELOG
    另外,还有下列参数约束:
    - 只更新 README
    ```
    
    ## 输出
    
    - `AGENTS.md`:跨平台通用项目指令,应该被长期维护。
    - `CLAUDE.md`:Claude Code 适配层,核心内容应与 `AGENTS.md` 保持一致。
    - `README.md`:项目介绍、快速开始和目录说明。
    - `CHANGELOG.md`:项目变更记录。
    - `.gitignore`:默认的安全与项目类型忽略规则。
    - `docs/`:项目文档根目录。
    - `docs/plans/`:计划文档固定目录;其余 `docs/` 文档在代码变化时也应及时同步更新。
    - `docs/contribution.bac`:默认 BAC 贡献托管文件;用户可通过 `--bac-file` 指定其它项目内路径。
    
    ## 配置
    
    - 配置文件:`init-project/config.yaml`
    - 关键配置节:
      - `language_mapping`
      - `bac_contribution`
      - `agents_required_sections`
      - `claude_required_sections`
      - `readme_required_sections`
      - `changelog_required_sections`
    - 这个 skill 的默认定位是“完整初始化”,不是只生成一份孤立文档。
    
    ## 备选用法(脚本/硬编码)
    
    如果你想直接在命令行下执行项目初始化,脚本入口最方便。
    
    ### 自动分析当前目录并生成文件
    
    ```bash
    python3 init-project/scripts/generate.py --auto
    ```
    
    ### 自动分析并覆盖已有文件
    
    ```bash
    python3 init-project/scripts/generate.py --auto --overwrite
    ```
    
    ### 只生成部分文档
    
    ```bash
    python3 init-project/scripts/generate.py --auto --only-readme
    python3 init-project/scripts/generate.py --auto --only-changelog
    ```
    
    ### 跳过部分输出
    
    ```bash
    python3 init-project/scripts/generate.py \
      --auto \
      --skip-readme \
      --skip-changelog \
      --skip-gitignore
    ```
    
    ### BAC 贡献记录
    
    ```bash
    # 默认开启:检查/安装 bac,并初始化 docs/contribution.bac
    python3 init-project/scripts/generate.py --auto
    
    # 指定项目内的其它 BAC 文件
    python3 init-project/scripts/generate.py --auto --bac-file docs/audit/contribution.bac
    
    # 随时显式关闭 BAC 初始化步骤
    python3 init-project/scripts/generate.py --auto --disable-bac
    ```
    
    关闭后,生成的 `AGENTS.md` 会明确 BAC 当前未启用,不再保留“默认且强制”的启用态指令。
    
    BAC 基于 <https://github.com/huangwb8/bensz-auto-contribution>,用于客观记录人类与 AI 的协作过程和证据,不替代最终署名、责任或合规判断。
    
    ## 常见问题
    
    ### Q:`AGENTS.md` 和 `CLAUDE.md` 到底谁是主文件?
    
    A:`AGENTS.md` 是单一真相来源;`CLAUDE.md` 是平台适配层。维护时应优先保证 `AGENTS.md` 的口径正确。
    
    ### Q:它会不会改到当前项目目录之外?
    
    A:不应该。这个 skill 的边界就是“当前目录内生成或更新项目文件”。
    
    ### Q:既然是自动化,是不是可以放心覆盖任何已有文件?
    
    A:不能这么理解。自动化不等于无脑覆盖。是否覆盖应由你显式决定,例如使用 `--overwrite`。
    
    ### Q:为什么 `.gitignore` 也算初始化结果的一部分?
    
    A:因为它直接关系到项目安全和仓库整洁度,尤其能防止敏感文件、系统文件和缓存文件被误提交。
    
  • SKILL.md 9.7 KB
    ---
    name: init-project
    description: 当用户明确要求初始化项目、创建项目指令文件、生成 AGENTS.md,或为已有项目补齐 AI 协作规范时使用。该 Skill 会分析项目结构,并生成或更新适用于当前项目的标准化协作文档与基础目录。
    metadata:
      author: Bensz Conan
      short-description: 完全自动生成 AI 项目指令文档并初始化标准 docs 目录
      keywords:
        - init-project
        - 项目初始化
        - AGENTS.md
        - CLAUDE.md
        - 项目指令
        - 项目规范
        - 自动分析项目
        - 检测项目类型
        - OpenAI Codex
        - Claude Code
        - 跨平台指令
        - "@引用语法"
        - SingleSourceofTruth
    ---
    
    # Init Project
    
    ## 目标
    
    当用户明确要求初始化项目、创建项目指令文件、生成 AGENTS.md,或为已有项目补齐 AI 协作规范时使用。本 Skill 分析项目结构,并生成或更新适用于当前项目的标准化协作文档与基础目录。
    
    ## 流程
    
    ### 输入
    
    输入为目标项目根目录及用户选择的初始化模式;可选输入包括项目名称/描述、工作流、输出开关、`--overwrite`、`--bac-file` 和 `--disable-bac`。输出路径必须位于当前项目目录内,现有治理文件和用户自定义章节应先识别再合并。
    
    ### 执行步骤
    
    #### 目标与边界
    
    为当前项目生成标准 AI 协作文档,让 Claude Code / OpenAI Codex CLI 等工具理解项目目标、工程原则、变更记录规则与协作边界。
    
    只允许在当前工作目录及其子目录内创建或修改文件。禁止写入父目录、其它项目、系统目录或用户级配置。脚本会在写入前校验输出路径,失败时立即停止。
    
    #### 核心约束
    
    - `AGENTS.md` 是唯一需要长期手动维护的通用指令源;`CLAUDE.md` 只做 Claude Code 适配,并通过 `@./AGENTS.md` 自动引用。
    - 生成模板统一放在 `init-project/templates/`:`AGENTS.md.template`、`CLAUDE.md.template`、`README.md.template`、`CHANGELOG.md.template`、`gitignore.yaml`。
    - 配置统一放在 `init-project/config.yaml`,版本号以 `skill_info.version` 为准;当前 BAC 配置在 `bac_contribution`。
    - 完整初始化必须补齐 `docs/` 与 `docs/plans/`;不默认创建项目根目录 `skills/`,保留项目已有的目录与内容。
    - 代码变化导致 `docs/` 中非 `plans/` 文档过时时,生成的项目指令必须要求同步更新。
    - 影响项目行为、结构、工作流、工程原则、指令文件或关键配置的变更,必须写入 `CHANGELOG.md` 的 `[Unreleased]`。
    
    #### BAC 贡献记录
    
    默认基于 `bensz-auto-contribution` / `bac` 记录人类、AI 与工具贡献证据:
    
    - 默认仓库:`https://github.com/huangwb8/bensz-auto-contribution`
    - 默认安装源:`git+https://github.com/huangwb8/bensz-auto-contribution.git`
    - 默认文件:`docs/contribution.bac`
    - Python 要求:`config.yaml:bac_contribution.min_python_version`,当前为 `3.10`
    - 默认开启;用户可随时通过 `--disable-bac` 显式关闭。关闭时生成的文档也必须说明当前已关闭且可重新启用。
    - 用户通过 `--bac-file` 指定项目内其它路径时,以用户指定为准;禁止把 `.bac` 文件写到项目目录外。
    
    BAC 是过程记录与辅助审计材料,不替代最终署名、责任或合规判断;不得记录敏感密钥、完整私有提示词或无关个人隐私。
    
    #### 推荐执行
    
    在目标项目根目录运行:
    
    ```bash
    python3 init-project/scripts/generate.py --auto
    ```
    
    常用参数:
    
    ```bash
    # 覆盖/强制更新已有文件
    python3 init-project/scripts/generate.py --auto --overwrite
    
    # 指定 BAC 文件,必须位于项目目录内
    python3 init-project/scripts/generate.py --auto --bac-file docs/audit/contribution.bac
    
    # 显式关闭默认 BAC 初始化
    python3 init-project/scripts/generate.py --auto --disable-bac
    
    # 只生成单类文档 / 跳过可选输出
    python3 init-project/scripts/generate.py --auto --only-readme
    python3 init-project/scripts/generate.py --auto --only-changelog
    python3 init-project/scripts/generate.py --auto --skip-readme --skip-gitignore
    ```
    
    手动模式只在用户明确给出项目信息时使用:
    
    ```bash
    python3 init-project/scripts/generate.py \
      --project-name "my-project" \
      --project-description "数据科学项目" \
      --workflow "数据获取 → 分析 → 可视化"
    ```
    
    #### 自动模式流程
    
    `--auto` 会依次完成:
    
    1. 验证输出目录必须位于当前工作目录内。
    2. 分析项目:从 README 提取名称/描述,按标志文件识别项目类型,生成最多 2 层目录树。
    3. 检测默认语言,失败时回退到简体中文。
    4. 完整初始化时创建 `docs/` 与 `docs/plans/`。
    5. 按配置决定是否启用 BAC:检查 Python 与 `bac` 包,必要时安装,初始化或验证 `.bac` 文件。
    6. 生成或智能合并 `AGENTS.md`、`CLAUDE.md`。
    7. 按条件生成 `README.md`、`CHANGELOG.md`、`.gitignore`。
    8. 输出生成文件、目录与项目分析摘要。
    
    项目类型识别标志:Python(`pyproject.toml`、`requirements.txt` 等)、Web(`package.json` 等)、Rust(`Cargo.toml`)、Go(`go.mod`)、Java(`pom.xml`/Gradle)、数据科学(`*.ipynb`、`*.R`、`environment.yml`)、文档(`docs/`、`mkdocs.yml`、`docusaurus.config.js`)。
    
    #### 智能合并策略
    
    当 `AGENTS.md` 或 `CLAUDE.md` 已存在时,默认智能合并而非直接覆盖:保留用户自定义的 `## 项目目标`、`## 核心工作流`、`## 变更边界` 及非标准章节;更新工程原则、默认语言、平台适配、`AGENTS.md` 必需章节与 `CLAUDE.md` 的 `@./AGENTS.md` 引用。`AGENTS.md` 中历史遗留的 `## 目录结构` 会被丢弃,避免回填为自定义章节;合并不符合预期时提示用户用 `--overwrite`。
    
    #### .gitignore 策略
    
    从 `templates/gitignore.yaml` 读取规则;缺少 PyYAML 或配置损坏时使用默认规则兜底。安全优先,默认忽略系统文件、IDE 配置、日志、临时文件、环境变量、密钥、凭证目录和常见构建/缓存产物。已有 `.gitignore` 在覆盖模式下会保留用户自定义规则。
    
    ### 输出
    
    #### 输出文件
    
    - `AGENTS.md`:跨平台通用项目指令,Single Source of Truth;必生成,智能合并。
    - `CLAUDE.md`:Claude Code 适配层,核心为 `@./AGENTS.md`;必生成,智能合并。
    - `README.md`、`CHANGELOG.md`、`.gitignore`:按需生成;`--overwrite` 可覆盖/合并。项目变更必须维护 `CHANGELOG.md`。
    - `docs/`、`docs/plans/`:完整初始化时自动补齐;计划文档固定放在 `./docs/plans/`。
    - `docs/contribution.bac`:默认 BAC 账本;`--bac-file` 可改,`--disable-bac` 可关。
    
    ### 输出管理
    
    #### BenszAPI 任务工作区
    
    
    ### 校验
    
    #### 交付前检查
    
    - [ ] `AGENTS.md` 包含必需章节:项目目标、核心工作流、工程原则、默认语言、联网与搜索、贡献记录、Codex CLI 特定说明、变更记录与版本、有机更新原则。
    - [ ] `CLAUDE.md` 正确通过 `@./AGENTS.md` 引用通用指令。
    - [ ] `docs/`、`docs/plans/` 已存在或无需本模式创建;未默认创建项目根目录 `skills/`。
    - [ ] BAC 已初始化/验证,或用户已显式使用 `--disable-bac`。
    - [ ] `.gitignore` 已生成/合并,且包含敏感文件忽略规则。
    - [ ] `CHANGELOG.md` 已创建或变更已记录。
    - [ ] 未写入当前项目目录之外的文件。
    
    ### 失败与恢复
    
    #### 错误处理
    
    - Windows GBK 等非 UTF-8 控制台不会因装饰性 Unicode 状态符号中止;脚本保留宿主编码,仅转义无法编码的字符,业务异常与退出码仍按原逻辑传播。
    - 输出目录越界、目标目录不存在或不是目录:停止。
    - `docs` / `docs/plans` 已存在但不是目录:停止。
    - BAC 安装、导入、初始化或验证失败:停止,并提示可用 `--disable-bac` 显式关闭。
    - 语言检测失败:回退到简体中文。
    - 项目类型无法识别:使用通用项目模板。
    - `PyYAML` 缺失:脚本继续运行,配置与 `.gitignore` 使用默认值。
    
    
    ## 约束
    
    <!-- BEGIN COMMON CONSTRAINTS -->
    <!-- Source-Hash: sha256:15120201e9e0c7569517261d57ecefb63ac279c26ed13876f8e95b6dc35854d3 -->
    <!-- Template-ID: skill-common-constraints; Template-Version: 1; Sync-Policy: exact-block -->
    
    ### 公共硬约束
    
    本块由 `docs/templates/skill-common-constraints.md` 统一维护;每个 `SKILL.md` 的 `## 约束` 必须逐字同步本块,不得在副本中改写公共规则。
    
    - 任务需要落盘时,使用唯一的 `./.bensz-api/task-{yyyymmdd-hhmm}-{简短描述}/` 根目录;共享材料放入 `shared/`,Skill 专属材料放入该 Skill 的 `input/`、`output/`、`log/`。
    - 正式交付物、源代码和正式计划按项目约定保存,不写入任务工作区;未经授权不覆盖、删除、迁移或远程写入。
    - 项目维护变更检查 BAC 可用性并记录需求、AI 产出、工具结果、文件改动和验证摘要;BAC 只做过程审计,不替代署名、责任或合规判断。
    - 不记录 API Key、访问令牌、密码、Cookie、环境/凭据文件、私有 Prompt、身份信息、本地用户名、主机名或不必要的大体积原始数据。
    - 文件路径必须规范化并限制在授权项目范围内;外部 URL、子进程和网络访问遵循最小权限,防止路径遍历、SSRF 和命令注入。
    - Skill 版本唯一记录在自身 `config.yaml:skill_info.version`;公开 API、协议、目录或配置变更同步文档与 `CHANGELOG.md`。
    - `bensz-collect-bugs` 是一个 Agent Skill;仅将 Bensz Agent Skill 或 Bensz 基础设施本身的设计缺陷交给它。先脱敏写入 `~/.bensz-skills/bugs/`,当前任务不中断,只有用户明确要求才公开上报,禁止直接修改用户已安装的 Skill 源码。
    
    <!-- End of canonical common constraints. -->
    <!-- END COMMON CONSTRAINTS -->
    

Comments (0)

Sign in to join the conversation.

No comments yet.

Reviews (0)

No reviews yet.