新闻详情

新闻详情

首页 / 资讯中心 / 详情

Claudian 贡献指南详解:Issue 规范、PR 要求、新 Provider 政策与本地开发验证全流程

发布时间:2026/9/14 3:31:34来源:尧图网络
Claudian 贡献指南详解:Issue 规范、PR 要求、新 Provider 政策与本地开发验证全流程
Claudian 贡献指南详解Issue 规范、PR 要求、新 Provider 政策与本地开发验证全流程【免费下载链接】claudianAn Obsidian plugin that embeds Claude Code/Codex as an AI collaborator in your vault项目地址: https://gitcode.com/GitHub_Trending/cl/claudianClaudian 是一个把 Claude Code、Codex、Grok、OpenCode、Pi 等编码 Agent 嵌入 Obsidian 侧边栏的插件。本文以仓库根目录的 CONTRIBUTING.md 为核心骨架结合仓库中的 Issue/PR 模板、CI 工作流、AGENTS.md 开发规则与 package.json 脚本配置系统讲解向该项目贡献代码前的检索规范、Issue 提交要素、Pull Request 的六段式描述要求、不接受新增 Provider 的维护边界以及npm install npm run dev之后如何跑通typecheck / lint / test / build完整验证套件。读完后你将知道一次合格的 Claudian 贡献从问题描述到验证闭环的完整标准。贡献总原则Issue 优先PR 聚焦CONTRIBUTING.md 开宗明义Issues 和 Pull Requests 都欢迎但Issue 是首选的贡献方式——只要你把问题和环境描述清楚维护者会审阅并尽力处理。这一定位贯穿了仓库的配套文件.github/ISSUE_TEMPLATE/bug_report.yml与.github/ISSUE_TEMPLATE/feature_request.yml把描述问题流程化成了强制表单.github/PULL_REQUEST_TEMPLATE.md把 PR 描述要求固化成了模板.github/workflows/ci.yml用自动化检查强制执行文档中的人工约定详见后文。开始前部分给出三条检索与范围纪律原文要点必须完整继承先搜索已有的 Issues 和 PRs避免重复提交对较大的改动先开 Issue在实现之前讨论清楚问题与范围每个 PR 只解决一个问题。无关的修复、重构、格式化改动、依赖更新都必须拆分提交。这三条在 PR 模板的 Checklist 中逐条对应This pull request addresses one focused problem...、I linked the relevant issue...可见文档约定与提交表单是一一对齐的。提交 Issue一个可复现、可诊断的完整描述文档要求一个有用的 Issue 必须让他人能够理解并复现问题需包含以下要素与 bug report 模板的字段完全对应你试图做什么实际发生了什么、你期望的是什么清晰的复现步骤或最小示例;版本信息五连Claudian 版本、Obsidian 版本、操作系统、Provider、Provider CLI 版本、安装方式相关的日志、截图或录屏。.github/ISSUE_TEMPLATE/bug_report.yml中的 Environment 区块正是这组字段的结构化落地且全部为必填项- Claudian version: - Obsidian version: - Operating system: - Provider: - Provider CLI version: - Provider CLI installation method:之所以强调Provider CLI 版本和安装方式是因为 Claudian 的运行时依赖外部 CLIspawn claude ENOENT这类问题在 Node 版本管理器场景下很常见见 README.md 的 Troubleshooting 一节缺了这一项维护者几乎无法定位。隐私红线文档明确要求在附带日志或截图前移除 API key、token、私有 vault 内容、个人路径等敏感信息。功能请求则要求从用户问题或未满足的使用场景出发——给出方案是加分项但解释为什么需要比规定怎么实现更重要。这一点在 feature request 模板里同样有体现Proposed solution字段是选填的而Problem or unmet use case是必填的。Pull RequestWhy / What / Why this approach / Validation / Impact / Context文档要求 PR 解决具体且定义清晰的问题并且 PR 描述必须解释六个维度。.github/PULL_REQUEST_TEMPLATE.md把这六个维度中的前五个做成了标题骨架文档要求模板小节内容要点WhyWhy解决什么问题、影响谁、为什么值得解决有对应 Issue 时链接WhatWhat Changed行为或代码层面的具体变化Why this approachWhy This Approach为什么这个设计合适包含有意义的备选方案与权衡ValidationValidation执行过的自动化测试与手动检查面向用户的改动需附截图或录屏ImpactImpact and Follow-ups已知限制、兼容性或数据风险、后续工作ContextChecklist存在对应 Issue 时必须链接或解释为何不需要在此之外文档还列出四条额外必须PR 模板 Checklist 的延伸行为变更和 Bug 修复必须新增或更新测试保持 Provider 与 Feature 的所有权边界避免共享 Feature 代码耦合到 Provider 内部实现避免引入新的生产依赖除非需求与权衡被明确说明行为或面向用户的配置发生变化时同步更新文档。这些边界不是空话。AGENTS.md 用一张依赖方向表定义了各区域的职责src/core/不得导入 Feature 代码、应用组合或 Provider 实现Feature 代码不得导入 Provider 实现必须通过核心注册表和契约访问 Provider 行为Provider 运行时和协议代码不得导入聊天视图或 Feature 控制器。PR 描述中避免耦合共享 Feature 代码到 Provider 内部这一条对应的正是这份架构规则。New Provider Policy为什么不接受新增 Provider 的 PR这是 CONTRIBUTING.md 中最具特色的章节文档明确写道Pull requests that add a new provider are not accepted.并给出四条维护与产品质量边界的理由单一维护者责任维护者合入后对每个集成负全责如果维护者自己不使用某个 Provider就无法长期负责任地测试和维护其集成功能一致性要求已集成的 Provider 必须提供广泛一致的功能集与用户体验过去的经验表明部分集成很难补齐到同等水平并保持可靠部分 CLI 能力不足例如 Antigravity CLI 没有暴露 ACP 或可比的集成协议Cursor CLI 无法完整自定义 system prompt不可持续的集成模式为每家模型厂商集成一个独立 CLI 并不可持续——OpenCode 和 Pi 已经通过 API 配置支持多家模型厂商Codex 和 Claude Code 也可以通过配置使用替代模型端点。在 Obsidian vault 内切换底层 harness 带来的额外价值有限却会持续产生集成与维护成本。文档同时给出了正确的出口可以开 Issue 描述未满足的 Provider 相关使用场景但不要提交新 Provider 的实现开 Issue 也不意味着该 Provider 会被加入。而改进现有 Provider 的贡献仍然欢迎前提是遵循聚焦 PR 的要求并保持跨 Provider 的一致体验。这个政策与仓库现状完全吻合。从源码结构看src/providers/ 下是claude/、codex/、grok/、opencode/、pi/五个 Provider 适配器加一个共享的acp/传输层每个 Provider 目录都有capabilities.ts与registration.tsAGENTS.md 要求不要假设 Provider 对等接线共享行为前检查每个 Provider 的capabilities.ts、registration.ts和 UI 配置。feature request 模板中的 Affected provider 下拉选项也正是这五个加一个 Other or new provider 入口——新 Provider 的场景被引导到 Issue 讨论通道而不是 PR 通道。本地开发Node 版本、dev 模式与 TDD 工作流环境与启动命令文档声明 Claudian 要求.node-version中声明的 Node.js 版本——当前该文件内容为24.16.0package.json 的engines字段对应约束为24 25CI 中actions/setup-node也直接读取node-version-file: .node-version三者严格一致。启动开发环境的命令npm install npm run dev从 package.json 的 scripts 看dev实际执行npm run build:css node esbuild.config.mjs即先构建模块化 CSS 再进入 esbuild 监听构建构建配置见 esbuild.config.mjs首次npm install会触发postinstall钩子执行 scripts/postinstall.mjs。先写失败测试再跑完整验证套件文档对开发工作流的要求是对 Bug 修复或新行为先添加或更新一个失败的测试再做让该测试通过的最小实现变更迭代过程中使用聚焦的检查命令提交 PR 前必须运行完整验证套件npm run typecheck npm run lint npm run test npm run build这四条命令在 package.json 中的真实展开如下可以直接对照理解每个环节在查什么命令实际执行说明npm run typechecktsc --noEmitTypeScript 全量类型检查tsconfig.jsonnpm run linteslint {src,tests}/**/*.ts --max-warnings0stylelint src/style/**/*.cssTS 与 CSS 双 lintESLint 零警告容忍eslint.config.mjs、stylelint.config.mjsnpm run testnode scripts/run-tests.js测试入口另提供test:unitjest见 scripts/run-jest.js、test:watch、test:coverage等子命令npm run buildnode scripts/build.mjs production生产构建经 esbuild.config.mjs 打包插件产物AGENTS.md 将同一套件写成默认全量检查npm run typecheck npm run lint npm run test npm run build并补充了test:watch、test:coverage等迭代用命令。测试目录镜像src/布局位于tests/unit/与tests/integration/之下例如 tests/unit/providers/、tests/integration/app/collab/为行为变更补测试这条 PR 要求有明确的落点。CI 如何强制执行这套验证.github/workflows/ci.yml把文档中的人工约定变成了流水线关卡每个 job 都对应一个可验证的约束workflow-lint用 actionlint 检查 workflow 文件本身lockfilenpm run check:lockfile即bun install --frozen-lockfile --ignore-scripts校验锁文件一致性——这解释了仓库同时存在bun.lock与package-lock.jsonqualitynpm ci后依次跑npm run typecheck、npm run lintNode 版本由.node-version决定testnpm ci后跑npm run testbuild依赖 quality 与 test 通过npm run build npm run check:performance即生产构建后还要过 scripts/check-startup-performance.mjs 的启动性能检查diff-hygiene仅 PR 触发用git diff --check检查变更行的空白错误dependency-review仅 PR 触发fail-on-severity: high——这从 CI 层面兜底了文档避免新生产依赖的要求cross-platform-smoke当变更触及 Collab 相关路径src/app/collab/*、src/core/collab/*等时在windows-latest与macos-latest矩阵上运行test:architecturescripts/check-architecture-boundaries.test.mjs、生产构建与test:cross-platform-collabscripts/run-cross-platform-collab-tests.js。换句话说本地跑通四条验证命令是 PR 的入场券而 CI 还额外覆盖锁文件、依赖安全、空白卫生和跨平台 Collab 冒烟。架构与领域规则以各级 AGENTS.md 为准CONTRIBUTING.md 的最后一句指出项目架构和按领域划分的开发规则记录在根 AGENTS.md 以及src/下的各作用域AGENTS.md中。这套scoped guide体系规定了编辑某个区域前必须先读最近的领域指南具体包括src/app/AGENTS.md应用服务的状态所有权与依赖方向例如FeatureHost是 Feature 侧的应用边界、ProviderHost是 Provider 侧的应用边界src/core/AGENTS.mdProvider 中立的运行时、注册表与类型契约src/features/chat/AGENTS.md 与 src/features/collab/AGENTS.md侧边栏聊天与 Collab 特性的编排规则;各 Provider 的 src/providers/claude/AGENTS.md、src/providers/codex/AGENTS.md、src/providers/grok/AGENTS.md、src/providers/opencode/AGENTS.md、src/providers/pi/AGENTS.mdsrc/style/AGENTS.md样式约定。根 AGENTS.md 则给出仓库级规则命名约定接口不加I前缀、文件用PascalCase.ts、文件夹kebab-case、导入不加.ts扩展名、生产代码禁用console.*、设置写入器必须合并而非替换 Provider 配置、TDD 工作流先建立失败测试且只 mock 环境、Obsidian 与 Provider 三类真实外部边界等。这些规则直接决定 PR 能否通过审查——文档保持 Provider 与 Feature 所有权边界的要求最终就是在这些指南定义的依赖方向上被执行。小结向 Claudian 贡献的完整路径可以浓缩为一张检查清单搜索已有 Issues/PRs大改动先开 Issue 讨论范围Bug 报告写全复现步骤与环境五连提交前脱敏功能请求先讲用户问题PR 单一聚焦描述覆盖 Why / What / Why this approach / Validation / Impact / Context 六要素补测试、不加新生产依赖、不跨 Provider 边界耦合新 Provider 一律走 Issue 通道不要提 PR本地按.node-version24.16.0配置 Nodenpm install npm run dev起步TDD 先写失败测试提交前跑typecheck / lint / test / build四件套并预期 CI 还会检查锁文件、依赖安全、空白卫生与跨平台 Collab 冒烟动手改某个目录前先读该目录最近的AGENTS.md领域指南。这套文档约定 模板固化 CI 强制的三层结构是理解 Claudian 贡献流程最准确的框架任何一条 CONTRIBUTING 中的软性要求几乎都能在仓库里找到一个对应的模板字段或 CI job 作为硬约束。【免费下载链接】claudianAn Obsidian plugin that embeds Claude Code/Codex as an AI collaborator in your vault项目地址: https://gitcode.com/GitHub_Trending/cl/claudian创作声明:本文部分内容由AI辅助生成(AIGC),仅供参考
网站建设高端定制企业官网
RELATED

相关资讯

更多精彩内容,欢迎继续阅读

较早相关资讯

最新相关资讯

MuJoCo MJX Barkour v0 四足模型解析:为 JAX 后端定制的高动态四足机器人 MJCF 配置 2026/9/14 4:10:37

MuJoCo MJX Barkour v0 四足模型解析:为 JAX 后端定制的高动态四足机器人 MJCF 配置

MuJoCo MJX Barkour v0 四足模型解析:为 JAX 后端定制的高动态四足机器人 MJCF 配置 【免费下载链接】mujoco Multi-Joint dynamics with Contact. A general purpose physics simulator. 项目地址: https://gitcode.com/GitHub_Trending/mu/mujoco 本文以 M…

阅读更多 →
PS证件照制作辅助软件:脚本、像素换算与批量排版实战 2026/9/14 4:10:37

PS证件照制作辅助软件:脚本、像素换算与批量排版实战

简介:Photoshop用户如需快速制作合规证件照,可关注这套辅助软件包,通常对应“证照大师完美版”。它主要面向设计师、摄影工作室,以及需要批量制作证件照的行政人员,目标是简化PS中尺寸裁剪、背景替换、曝光美化与多张排…

阅读更多 →
LMCache KV Cache 源码深度解析:cache_engine.py 缓存机制完整拆解 2026/9/14 4:10:37

LMCache KV Cache 源码深度解析:cache_engine.py 缓存机制完整拆解

LMCache KV Cache 源码深度解析:cache_engine.py 缓存机制完整拆解 【免费下载链接】LMCache LMCache: Supercharge Your LLM with the Fastest KV Cache Layer 项目地址: https://gitcode.com/GitHub_Trending/lm/LMCache 本文以 cache_engine.py 为主线&am…

阅读更多 →
深入拆解 LMCache 的 KV 缓存引擎:一条请求的完整旅程 2026/9/14 4:10:37

深入拆解 LMCache 的 KV 缓存引擎:一条请求的完整旅程

深入拆解 LMCache 的 KV 缓存引擎:一条请求的完整旅程 【免费下载链接】LMCache LMCache: Supercharge Your LLM with the Fastest KV Cache Layer 项目地址: https://gitcode.com/GitHub_Trending/lm/LMCache 2 万 token 的长文档问答里,每一轮新…

阅读更多 →
网页嵌入QQ群代码:从原理到排错完整指南 2026/9/14 4:10:37

网页嵌入QQ群代码:从原理到排错完整指南

简介:面向需要快速汇聚QQ群成员的网站运营者与社群管理员,这份压缩包提供了一套“Q群代加”场景下的网页嵌入QQ群解决方案。核心脚本由monkeysbk团队以programav2版本发布,主要解决访客无需手动搜索QQ群号,刷新网页即可一键唤起加…

阅读更多 →
零基础玩转ESP32:从SD卡到WiFi,打造自己的音乐播放器 2026/9/14 4:07:37

零基础玩转ESP32:从SD卡到WiFi,打造自己的音乐播放器

/* MD / 富文本中的 .toc(含博客园搬家等嵌套结构);.toc-box 在侧栏,不受影响 */#content_views .toc,/* 编辑器常在目录前后插入空 p(:empty 仍占 20px),一并去掉避免顶空隙 */#content_views.markdown_views > p:empty:has(+ .toc),#content_views.markdown_views …

阅读更多 →

今日资讯

本周资讯

本月资讯

看完文章仍有疑问?

联系尧图顾问,获取一对一建站咨询

立即免费咨询 📞 400-888-8888
📞