A local-first multi-agent app development platform, built on PenguinHarness
Complete the GitHub community standards, under .github/ (#514)
Yaowei Zhengf61c32e29eea
diff --git a/.agents/skills/penguin-harness-dev/SKILL.md b/.agents/skills/penguin-harness-dev/SKILL.mdindex 730be0ef..34b4c925 100644--- a/.agents/skills/penguin-harness-dev/SKILL.md+++ b/.agents/skills/penguin-harness-dev/SKILL.md@@ -36,7 +36,7 @@ pnpm --filter @prismshadow/penguin-web test| Changed | Run || --- | --- |-| Markdown only — changelog, `CONTRIBUTING.md`, `.agents/`, README | `pnpm format:check` |+| Markdown only — changelog, `.github/CONTRIBUTING.md`, `.agents/`, README | `pnpm format:check` || `packages/docs/content/**`, blog posts under `packages/landing/content/**` | `format:check` + the `docs` and `landing` package tests (search index, blog fixtures) || `packages/skills/skills/**` | the `skills` package test + `docs`'s `skills-sync.test.ts` || The model catalog | core `model-catalog.test.ts`, web `model-grouping.test.ts` and `protocol-path.test.ts`, server `models.test.ts` |diff --git a/.github/CODE_OF_CONDUCT.md b/.github/CODE_OF_CONDUCT.mdnew file mode 100644index 00000000..2456cfb3--- /dev/null+++ b/.github/CODE_OF_CONDUCT.md@@ -0,0 +1,85 @@+# Contributor Covenant Code of Conduct++[中文版](https://github.com/Prism-Shadow/penguin-harness/blob/main/.github/CODE_OF_CONDUCT.zh.md)++## Our Pledge++We as members, contributors, and leaders pledge to make participation in our community a harassment-free experience for everyone, regardless of age, body size, visible or invisible disability, ethnicity, sex characteristics, gender identity and expression, level of experience, education, socio-economic status, nationality, personal appearance, race, caste, color, religion, or sexual identity and orientation.++We pledge to act and interact in ways that contribute to an open, welcoming, diverse, inclusive, and healthy community.++## Our Standards++Examples of behavior that contributes to a positive environment for our community include:++* Demonstrating empathy and kindness toward other people+* Being respectful of differing opinions, viewpoints, and experiences+* Giving and gracefully accepting constructive feedback+* Accepting responsibility and apologizing to those affected by our mistakes, and learning from the experience+* Focusing on what is best not just for us as individuals, but for the overall community++Examples of unacceptable behavior include:++* The use of sexualized language or imagery, and sexual attention or advances of any kind+* Trolling, insulting or derogatory comments, and personal or political attacks+* Public or private harassment+* Publishing others' private information, such as a physical or email address, without their explicit permission+* Other conduct which could reasonably be considered inappropriate in a professional setting++## Enforcement Responsibilities++Community leaders are responsible for clarifying and enforcing our standards of acceptable behavior and will take appropriate and fair corrective action in response to any behavior that they deem inappropriate, threatening, offensive, or harmful.++Community leaders have the right and responsibility to remove, edit, or reject comments, commits, code, wiki edits, issues, and other contributions that are not aligned to this Code of Conduct, and will communicate reasons for moderation decisions when appropriate.++## Scope++This Code of Conduct applies within all community spaces, and also applies when an individual is officially representing the community in public spaces. Examples of representing our community include using an official e-mail address, posting via an official social media account, or acting as an appointed representative at an online or offline event.++## Enforcement++Instances of abusive, harassing, or otherwise unacceptable behavior may be reported to the community leaders responsible for enforcement at <[email protected]>. All complaints will be reviewed and investigated promptly and fairly.++All community leaders are obligated to respect the privacy and security of the reporter of any incident.++## Enforcement Guidelines++Community leaders will follow these Community Impact Guidelines in determining the consequences for any action they deem in violation of this Code of Conduct:++### 1. Correction++**Community Impact**: Use of inappropriate language or other behavior deemed unprofessional or unwelcome in the community.++**Consequence**: A private, written warning from community leaders, providing clarity around the nature of the violation and an explanation of why the behavior was inappropriate. A public apology may be requested.++### 2. Warning++**Community Impact**: A violation through a single incident or series of actions.++**Consequence**: A warning with consequences for continued behavior. No interaction with the people involved, including unsolicited interaction with those enforcing the Code of Conduct, for a specified period of time. This includes avoiding interactions in community spaces as well as external channels like social media. Violating these terms may lead to a temporary or permanent ban.++### 3. Temporary Ban++**Community Impact**: A serious violation of community standards, including sustained inappropriate behavior.++**Consequence**: A temporary ban from any sort of interaction or public communication with the community for a specified period of time. No public or private interaction with the people involved, including unsolicited interaction with those enforcing the Code of Conduct, is allowed during this period. Violating these terms may lead to a permanent ban.++### 4. Permanent Ban++**Community Impact**: Demonstrating a pattern of violation of community standards, including sustained inappropriate behavior, harassment of an individual, or aggression toward or disparagement of classes of individuals.++**Consequence**: A permanent ban from any sort of public interaction within the community.++## Attribution++This Code of Conduct is adapted from the [Contributor Covenant][homepage], version 2.1, available at [https://www.contributor-covenant.org/version/2/1/code_of_conduct.html][v2.1].++Community Impact Guidelines were inspired by [Mozilla's code of conduct enforcement ladder][Mozilla CoC].++For answers to common questions about this code of conduct, see the FAQ at [https://www.contributor-covenant.org/faq][FAQ]. Translations are available at [https://www.contributor-covenant.org/translations][translations].++[homepage]: https://www.contributor-covenant.org+[v2.1]: https://www.contributor-covenant.org/version/2/1/code_of_conduct.html+[Mozilla CoC]: https://github.com/mozilla/diversity+[FAQ]: https://www.contributor-covenant.org/faq+[translations]: https://www.contributor-covenant.org/translationsdiff --git a/.github/CODE_OF_CONDUCT.zh.md b/.github/CODE_OF_CONDUCT.zh.mdnew file mode 100644index 00000000..adf20805--- /dev/null+++ b/.github/CODE_OF_CONDUCT.zh.md@@ -0,0 +1,87 @@+# 贡献者公约++[English](CODE_OF_CONDUCT.md)++## 我们的承诺++身为社区成员、贡献者和领袖,我们承诺使社区参与者不受骚扰,无论其年龄、体型、可见或不可见的缺陷、族裔、性征、性别认同和表达、经验水平、教育程度、社会与经济地位、国籍、相貌、种族、种姓、肤色、宗教信仰、性倾向或性取向如何。++我们承诺以有助于建立开放、友善、多样化、包容、健康社区的方式行事和互动。++## 我们的准则++有助于为我们的社区创造积极环境的行为例子包括但不限于:++* 表现出对他人的同情和善意+* 尊重不同的主张、观点和感受+* 提出和大方接受建设性意见+* 承担责任并向受我们错误影响的人道歉+* 注重社区共同诉求,而非个人得失++不当行为例子包括:++* 使用情色化的语言或图像,及性引诱或挑逗+* 嘲弄、侮辱或诋毁性评论,以及人身或政治攻击+* 公开或私下的骚扰行为+* 未经他人明确许可,公布他人的私人信息,如物理或电子邮件地址+* 其他有理由认定为违反职业操守的不当行为++## 责任和权力++社区领袖有责任解释和落实我们所认可的行为准则,并妥善公正地对他们认为不当、威胁、冒犯或有害的任何行为采取纠正措施。++社区领导有权力和责任删除、编辑或拒绝或拒绝与本行为准则不相符的评论(comment)、提交(commits)、代码、维基(wiki)编辑、议题(issues)或其他贡献,并在适当时机知采取措施的理由。++## 适用范围++本行为准则适用于所有社区场合,也适用于在公共场所代表社区时的个人。++代表社区的情形包括使用官方电子邮件地址、通过官方社交媒体帐户发帖或在线上或线下活动中担任指定代表。++## 监督++辱骂、骚扰或其他不可接受的行为可通过 <[email protected]> 向负责监督的社区领袖报告。 所有投诉都将得到及时和公平的审查和调查。++所有社区领袖都有义务尊重任何事件报告者的隐私和安全。++## 处理方针++社区领袖将遵循下列社区处理方针来明确他们所认定违反本行为准则的行为的处理方式:++### 1. 纠正++**社区影响**:使用不恰当的语言或其他在社区中被认定为不符合职业道德或不受欢迎的行为。++**处理意见**:由社区领袖发出非公开的书面警告,明确说明违规行为的性质,并解释举止如何不妥。或将要求公开道歉。++### 2. 警告++**社区影响**:单个或一系列违规行为。++**处理意见**:警告并对连续性行为进行处理。在指定时间内,不得与相关人员互动,包括主动与行为准则执行者互动。这包括避免在社区场所和外部渠道中的互动。违反这些条款可能会导致临时或永久封禁。++### 3. 临时封禁++**社区影响**: 严重违反社区准则,包括持续的不当行为。++**处理意见**: 在指定时间内,暂时禁止与社区进行任何形式的互动或公开交流。在此期间,不得与相关人员进行公开或私下互动,包括主动与行为准则执行者互动。违反这些条款可能会导致永久封禁。++### 4. 永久封禁++**社区影响**:行为模式表现出违反社区准则,包括持续的不当行为、骚扰个人或攻击或贬低某个类别的个体。++**处理意见**:永久禁止在社区内进行任何形式的公开互动。++## 参见++本行为准则改编自 [Contributor Covenant][homepage] 2.1 版, 参见 [https://www.contributor-covenant.org/version/2/1/code_of_conduct.html][v2.1]。++社区处理方针灵感来源于 [Mozilla's code of conduct enforcement ladder][Mozilla CoC]。++有关本行为准则的常见问题的答案,参见 [https://www.contributor-covenant.org/faq][FAQ]。 其他语言翻译参见 [https://www.contributor-covenant.org/translations][translations]。++[homepage]: https://www.contributor-covenant.org+[v2.1]: https://www.contributor-covenant.org/version/2/1/code_of_conduct.html+[Mozilla CoC]: https://github.com/mozilla/diversity+[FAQ]: https://www.contributor-covenant.org/faq+[translations]: https://www.contributor-covenant.org/translationsdiff --git a/CONTRIBUTING.md b/.github/CONTRIBUTING.mdsimilarity index 74%rename from CONTRIBUTING.mdrename to .github/CONTRIBUTING.mdindex af27d9f4..9ff761c3 100644--- a/CONTRIBUTING.md+++ b/.github/CONTRIBUTING.md@@ -1,8 +1,14 @@# Contributing to PenguinHarness+[中文版](CONTRIBUTING.zh.md)+Thanks for helping build PenguinHarness! This guide covers the workspace setup, dailycommands, quality gates, and the repo's working rules.+Participation is governed by the [Code of Conduct](CODE_OF_CONDUCT.md). A security+problem does not go in a public issue — the [security policy](SECURITY.md) says where to+send it instead.+## Prerequisites- Node >= 24@@ -87,15 +93,15 @@ Copy `.env.example` to `.env` for model credentials in development.A pnpm monorepo (TypeScript, Node >= 24). One install ships four layers that share asingle data directory (`~/.penguin/data`) and a single message protocol (OmniMessage):-| Package | Name | Role |-| ------------------------------------ | ----------------------------- | ------------------------------------------------------------------------------------------------------- |-| [`packages/core`](packages/core) | `@prismshadow/penguin-core` | SDK & engine: ReAct loop, OmniMessage protocol, LLM/Environment interface contracts, Agent State, Trace |-| [`packages/cli`](packages/cli) | `@prismshadow/penguin-cli` | The `penguin` command: REPL, one-shot runs, model & vault config, service launcher |-| [`packages/server`](packages/server) | `@prismshadow/penguin-server` | Web backend: HTTP API + SSE streaming, multi-user auth, Project authorization, usage stats |-| [`packages/web`](packages/web) | `@prismshadow/penguin-web` | Web App: multi-session chat, Agent/skill/model management, Trace observability, evaluation center |-| [`packages/skills`](packages/skills) | `@prismshadow/penguin-skills` | Built-in skill library (agent creation, benchmarking, evaluation, optimization, …) |-| [`packages/landing`](packages/landing) | — | Product landing page (this repo's website) |-| [`packages/docs`](packages/docs) | — | Documentation site (bilingual, deployed under `/docs/`) |+| Package | Name | Role |+| ----------------------------------------- | ----------------------------- | ------------------------------------------------------------------------------------------------------- |+| [`packages/core`](../packages/core) | `@prismshadow/penguin-core` | SDK & engine: ReAct loop, OmniMessage protocol, LLM/Environment interface contracts, Agent State, Trace |+| [`packages/cli`](../packages/cli) | `@prismshadow/penguin-cli` | The `penguin` command: REPL, one-shot runs, model & vault config, service launcher |+| [`packages/server`](../packages/server) | `@prismshadow/penguin-server` | Web backend: HTTP API + SSE streaming, multi-user auth, Project authorization, usage stats |+| [`packages/web`](../packages/web) | `@prismshadow/penguin-web` | Web App: multi-session chat, Agent/skill/model management, Trace observability, evaluation center |+| [`packages/skills`](../packages/skills) | `@prismshadow/penguin-skills` | Built-in skill library (agent creation, benchmarking, evaluation, optimization, …) |+| [`packages/landing`](../packages/landing) | — | Product landing page (this repo's website) |+| [`packages/docs`](../packages/docs) | — | Documentation site (bilingual, deployed under `/docs/`) |Responsibilities split by source of truth: the **SDK** owns protocol and execution(message parsing, the agent loop, tools), the **Server** owns the multi-user runtime@@ -113,7 +119,7 @@ pnpm typecheckpnpm test # unit suites for every package```-Working on this repo with a coding agent: [`.agents/skills/penguin-harness-dev/`](.agents/skills/penguin-harness-dev/SKILL.md)+Working on this repo with a coding agent: [`.agents/skills/penguin-harness-dev/`](../.agents/skills/penguin-harness-dev/SKILL.md)collects the conventions that are easy to get wrong from the outside — the two-repo symlinklayout, the CI-parity chain, the record-and-ship contract, the model catalog's pricing rules,and the seams that are intentional. `.claude` is a symlink to `.agents`, so a Claude Code@@ -139,7 +145,7 @@ pnpm test:e2e # core live-model e2e, need(released versions' folders are frozen) — an H1 title, the `Date` / `Type` / `Scope` /`PR` / `Issue` / `Breaking` metadata block, the counterpart link, then a lead paragraphand bespoke sections. There is no index file to update. The format is documented in- [`changelog/README.md`](changelog/README.md). Related changes may share one entry+ [`changelog/README.md`](../changelog/README.md). Related changes may share one entryfile (extending its sections) instead of opening a new file per small change.- **A release ships its own announcement**: `changelog/<version>/RELEASE.md` is publishedverbatim as the GitHub Release body. Write it during release preparation and **commit it@@ -157,6 +163,19 @@ pnpm test:e2e # core live-model e2e, need`node packages/landing/scripts/capture-readme-demo.mjs` (build first; needs Playwrightchromium). Regenerate rather than hand-editing.+## Reporting a bug or proposing a feature++Open an issue from the [issue forms](https://github.com/Prism-Shadow/penguin-harness/issues/new/choose).+A bug report is worth far more with the version (`penguin version`), how PenguinHarness+was installed, the OS, and whether the problem survives a fresh data root+(`PENGUIN_HOME=/tmp/penguin-check penguin ...`) — that last one separates a code defect+from a state left behind by an earlier version. Never paste an API key, a bot token,+`system_config.yaml`, or a `.env` into an issue: the data root holds provider credentials+in plain text, and an issue is public and permanent.++Questions and usage help belong on [Discord](https://discord.gg/eFHKqqcU3D) or in the+WeChat group, not in the issue tracker.+## Pull requests- Branch from `main`; keep PRs focused on one topic.@@ -164,3 +183,8 @@ pnpm test:e2e # core live-model e2e, needchanges in the PR body.- New user-facing behavior should come with tests, and with docs updates when it changesdocumented behavior (README, docs site).+- Write the title and body in English, and list what you actually ran under a+ `## Verification` heading. The [pull request template](PULL_REQUEST_TEMPLATE.md) is+ filled in for you when you open the PR.+- Pull requests are squash-merged, so one PR lands on `main` as one commit. Merging needs+ one approving review and every review thread resolved.diff --git a/.github/CONTRIBUTING.zh.md b/.github/CONTRIBUTING.zh.mdnew file mode 100644index 00000000..8366ac05--- /dev/null+++ b/.github/CONTRIBUTING.zh.md@@ -0,0 +1,160 @@+# 参与 PenguinHarness 开发++[English](CONTRIBUTING.md)++感谢你参与建设 PenguinHarness!本指南涵盖工作区搭建、日常命令、质量门禁,以及仓库的工作规则。++参与本项目受 [行为准则](CODE_OF_CONDUCT.zh.md) 约束。安全问题不要开公开 issue——+[安全策略](SECURITY.zh.md) 说明了应该发往何处。++## 前置条件++- Node >= 24+- pnpm 11(`corepack enable` 或 `npm install -g pnpm`)++## 搭建与日常命令++```bash+pnpm install+pnpm build # 先构建:core 的导出指向 dist/++pnpm dev # 服务端 + Web 一起启动(带前缀日志,依赖只构建一次)+pnpm dev:server # 服务端,127.0.0.1:7368(不是已安装 server 的 7364)+pnpm dev:web # Web App(Vite),127.0.0.1:7365,/api 代理到 7368+pnpm dev:docs # 文档站(Vite),127.0.0.1:7367+pnpm dev:landing # 落地页(Vite),127.0.0.1:7366+pnpm penguin ... # 从源码运行 CLI;`penguin web` 服务在 127.0.0.1:7369+pnpm desktop # 从源码运行桌面应用(先全量构建,再启动 Electron)++BASE_PATH=/ pnpm build:site # 完全按 Pages 部署的方式组装落地页 + 文档+```++每条 dev 命令都会先执行 `scripts/dev-prebuild.mjs`。它在一把用于串行化并发调用的锁之后,+**自动保持 `pnpm install` 处于最新状态**——全新 clone 或拉到的 lockfile 变更会在启动前先安装,+而已经最新的工作树不付出任何代价(lockfile 的哈希会被打戳记录)——随后预构建工作区依赖+(skills、core),并对背靠背的构建去重:同时启动 `dev:server` 与 `dev:web`(或直接 `pnpm dev`),+安装与构建各只发生一次。当这次构建改变了 skills/core 的产物时,预处理步骤还会清掉 Web App 的+Vite 依赖缓存(`packages/web/node_modules/.vite`)——该缓存仅以 lockfile/配置为键,否则会继续把+上一版 core 喂给浏览器。`dev:docs` / `dev:landing` 只跑安装检查(`--install-only`)。++绕开 dev 命令时有一条规则:**通过 pnpm 重新构建 skills/core,并按此顺序**(`pnpm build`,或重启+`pnpm dev`)——工作区使用注入式依赖(pnpm-workspace.yaml 中的 `injectWorkspacePackages`),因此+web/server 消费的是快照副本,只有当该包的 `build` 脚本经由 pnpm 运行时才会重新同步+(`syncInjectedDepsAfterScripts`)。在 packages/core 里直接跑 `npx tsup` 会更新+`packages/core/dist`,却把那些快照——以及任何已经填充的 Vite 依赖缓存——留在旧构建上;如果手工重建+之后,正在运行的开发 Web App 仍在提供陈旧的 core,删掉 `packages/web/node_modules/.vite` 再重启。++会触及数据的开发入口默认使用各自独立的数据根目录,与已安装 CLI/server 的 `~/.penguin/data`+分开——在仓库上折腾永远不会把状态与你真实的 Agent 混在一起。`pnpm dev`、`pnpm dev:server` 与+`pnpm desktop` 共用 `~/.penguin/dev-data`;`pnpm penguin` 独占 `~/.penguin/dev-data-cli`,因为一个+数据根目录同时只接纳一个 server(`<root>/server.lock`),而开发版 CLI 的 `penguin web` 恰恰就是那个+随后会让 Agent 去执行 `pnpm dev` 的 harness——共用根目录时,那个 Agent 的 `dev:server` 会被 harness+自己的锁挡住而拒绝启动(正是这种共存关系也已经为它分配了 7369 端口,见+`packages/core/src/internal/ports.ts`)。若仍要让某条开发 CLI 命令对准 `pnpm dev` 的数据集,就为该条+命令单独声明——`PENGUIN_HOME=~/.penguin/dev-data pnpm penguin ...`,或在支持的子命令上使用+`--root`。需要另一个根目录?只为需要它的那一条命令内联传入 `PENGUIN_HOME`+(`PENGUIN_HOME=~/.penguin/dev-data-<topic> pnpm dev`)——绝不要把它 export 进 shell:上述默认值仅在+该变量未设置或为空时才生效(`scripts/run-with-env.mjs`),因此一个已导出的值会静默盖过全部默认值;+而导出 `PENGUIN_HOME=~/.penguin/data` 会把 `pnpm dev:server` 放到发行版/CLI 的根目录上,那里已经有+一个运行中的桌面应用持有锁。桌面开发外壳还多隔离一层:未打包的运行会取一个带 dev 后缀的应用标识+(`PenguinHarness-Dev`),拥有自己的 userData 目录、单实例锁与固定端口,并且即使在没有该环境变量的+情况下启动(`pnpm --dir packages/desktop start`)也默认使用 `~/.penguin/dev-data`——因此它可以与已+安装的发行版并排运行,两个实例互不可见。每次未打包启动都会打印它选中的这一对:+`[shell] dev instance '<name>' on data root <root>`。++这次拆分带来了两处一次性变化。此前直接执行 `pnpm --dir packages/desktop start` 跑在+`~/.penguin/data`(发行版/CLI 根目录)上,现在跑在 `~/.penguin/dev-data`,因此那样创建的会话不再出现+在窗口里——若要刻意对着发行版根目录工作,用 `PENGUIN_HOME=~/.penguin/data` 启动。另外开发外壳的+userData 目录随其名称一并搬家,Chromium 配置文件也跟着走,因此窗口按 origin 存储的偏好(主题、语言、+布局)与记住的端口会重置一次。注意该标识是一个固定名称,而非每个工作副本一个:两份工作副本同时运行+桌面外壳仍会共用它,第二次启动会聚焦到第一个窗口而不是自己开一个——换一个 `PENGUIN_HOME` 也改变不了+这一点,因为它移动的是数据根目录,不是标识。++开发环境下的模型凭据:把 `.env.example` 复制为 `.env`。++## 仓库结构++一个 pnpm monorepo(TypeScript,Node >= 24)。一次安装交付四个层次,它们共享同一个数据目录+(`~/.penguin/data`)与同一套消息协议(OmniMessage):++| 包 | 名称 | 职责 |+| ----------------------------------------- | ----------------------------- | --------------------------------------------------------------------------- |+| [`packages/core`](../packages/core) | `@prismshadow/penguin-core` | SDK 与引擎:ReAct 循环、OmniMessage 协议、LLM/Environment 接口契约、Agent State、Trace |+| [`packages/cli`](../packages/cli) | `@prismshadow/penguin-cli` | `penguin` 命令:REPL、单次运行、模型与 vault 配置、服务启动器 |+| [`packages/server`](../packages/server) | `@prismshadow/penguin-server` | Web 后端:HTTP API + SSE 流式传输、多用户认证、Project 鉴权、用量统计 |+| [`packages/web`](../packages/web) | `@prismshadow/penguin-web` | Web App:多会话聊天,Agent/Skill/模型管理,Trace 可观测性,评测中心 |+| [`packages/skills`](../packages/skills) | `@prismshadow/penguin-skills` | 内置 Skill 库(Agent 创建、基准测试、评测、优化,……) |+| [`packages/landing`](../packages/landing) | — | 产品落地页(本仓库的官网) |+| [`packages/docs`](../packages/docs) | — | 文档站(双语,部署在 `/docs/` 下) |++职责按事实来源划分:**SDK** 拥有协议与执行(消息解析、Agent 循环、工具),**Server** 拥有多用户运行时+(认证、SSE 流式传输、定时任务),而 `~/.penguin/data` 下的**文件层**拥有一切可编辑与被记录的东西+(Prompt、Skill、密钥、Trace)。完整对照见+[架构 → 职责划分](https://penguin.ooo/docs/architecture)。++## 质量门禁++以下每一项 CI 都会在每个 PR 上运行——推送前请先在本地跑一遍:++```bash+pnpm format:check # prettier+pnpm typecheck+pnpm test # 每个包的单元测试+```++用编码 Agent 在本仓库上开发:[`.agents/skills/penguin-harness-dev/`](../.agents/skills/penguin-harness-dev/SKILL.md)+收集了那些从外部看最容易搞错的约定——双仓库软链接布局、CI 同链路验证、record-and-ship 契约、模型目录的+定价规则,以及那些有意为之的接缝。`.claude` 是指向 `.agents` 的软链接,因此 Claude Code 会话与其他任何+Agent 读到的是同一个目录。++端到端测试(本地可选,较慢):++```bash+npx playwright install chromium # 一次即可+pnpm --filter @prismshadow/penguin-web test:e2e # 针对 mock LLM 的浏览器 e2e+pnpm test:e2e # core 的真实模型 e2e,需要 DEEPSEEK_API_KEY+```++## 工作规则++- **英文是本仓库的工作语言**——代码、注释、错误与日志信息、测试名与 fixture、包元数据,以及面向开发者+ 的文档。中文只出现在它本身就是内容的地方:zh 的 i18n 词条与字段(`strings.ts` 词典、CLI 的+ `i18n.ts`、`titleZh`、`short_description_zh`)、`*.zh.md` 文档,以及断言 zh i18n 输出或验证 CJK+ 特有行为的测试字面量。+- **每次改动都随附一条 changelog 条目,中英各一份**:新增+ `changelog/unreleased/YYYY-MM-DD-<semantic-id>.md` 及其 `.zh.md` 对应文件(已发布版本的目录已冻结)+ ——一个 H1 标题、`Date` / `Type` / `Scope` / `PR` / `Issue` / `Breaking` 元数据块、对应文件的链接,+ 然后是引导段与按内容命名的小节。没有索引文件需要更新。格式见+ [`changelog/README.zh.md`](../changelog/README.zh.md)。相关联的改动可以共用一个条目文件(扩展它的+ 小节),不必为每个小改动都新开一个文件。+- **每次发布随附自己的公告**:`changelog/<version>/RELEASE.md` 会被原样发布为 GitHub Release 正文。+ 在发布准备期间撰写,并**在打 tag 之前提交**——发布工作流是从 tag 的 checkout 里读它的,事后添加的+ 文件永远到不了 Release 页面。缺少它时,工作流退回到 GitHub 自动生成的说明。+- **发布准备要提升仓库版本号**:那个把 `changelog/unreleased/` 改名的 `release: X.Y.Z` PR,同时也要把+ 根目录及每个 `packages/*/package.json` 的 `version`、以及 core 的 `VERSION` 常量+ (`packages/core/src/index.ts`)提升到发布版本。发布工作流会拒绝版本号与仓库不一致的 tag 推送,+ 因此漏掉提升会在发布任何东西之前就失败(v0.2.1 曾在仓库还是 0.2.0 时被打了 tag,此后每个开发构建+ 都在提示有更新,直到仓库追上为止)。+- `assets/readme/` 下的 README 素材是生成物——基准测试图表由落地页的基准数据生成,演示截图由+ `node packages/landing/scripts/capture-readme-demo.mjs` 生成(需先构建;需要 Playwright chromium)。+ 请重新生成,而不要手工编辑。++## 报告缺陷或提出功能建议++从 [issue 表单](https://github.com/Prism-Shadow/penguin-harness/issues/new/choose) 提交。一份缺陷报告+附上版本(`penguin version`)、PenguinHarness 的安装方式、操作系统,以及问题是否在全新的数据根目录上+依然出现(`PENGUIN_HOME=/tmp/penguin-check penguin ...`),价值会高得多——最后这一条能把代码缺陷与+旧版本遗留的状态区分开。永远不要把 API Key、机器人 Token、`system_config.yaml` 或 `.env` 贴进+issue:数据根目录以明文保存 Provider 凭据,而 issue 是公开且永久的。++提问与使用求助请去 [Discord](https://discord.gg/eFHKqqcU3D) 或微信群,不要发到 issue 区。++## Pull Request++- 从 `main` 拉分支;一个 PR 只聚焦一个主题。+- 确保 CI 全绿(build、format、typecheck、test),并在 PR 正文中描述对用户可见的变化。+- 新增的用户可见行为应当带上测试;当它改变了已被文档记录的行为时(README、文档站),还要更新文档。+- 标题与正文用英文撰写,并在 `## Verification` 小节下列出你实际运行过的内容。开 PR 时+ [Pull Request 模板](PULL_REQUEST_TEMPLATE.md) 会自动填入。+- PR 采用 squash 合并,一个 PR 在 `main` 上落成一次提交。合并需要一位审阅者批准,并且所有评审+ 讨论串都已解决。diff --git a/.github/ISSUE_TEMPLATE/bug_report.yml b/.github/ISSUE_TEMPLATE/bug_report.ymlnew file mode 100644index 00000000..f238c4cd--- /dev/null+++ b/.github/ISSUE_TEMPLATE/bug_report.yml@@ -0,0 +1,80 @@+name: Bug report+description: Something in PenguinHarness does not do what it says it does.+labels: ["bug"]+body:+ - type: markdown+ attributes:+ value: |+ Please search the open issues first, and check whether the newest release already fixes it — PenguinHarness has no maintenance branches, so a fix only ever arrives in a later version.++ **Never paste credentials.** A data root holds provider API keys, messaging bot tokens and Vault entries in readable form, so `system_config.yaml`, `.env`, a Trace and a full log are all likely to carry a secret. Quote the few lines that matter. If the bug *is* a leak or another security problem, do not file it here — follow the [security policy](https://github.com/Prism-Shadow/penguin-harness/blob/main/.github/SECURITY.md).++ - type: textarea+ id: summary+ attributes:+ label: What happened+ description: What you did, what you expected, and what happened instead.+ validations:+ required: true++ - type: textarea+ id: steps+ attributes:+ label: Steps to reproduce+ description: The shortest sequence that shows the problem. A prompt, a command, or a few clicks is enough — say which Agent, model and approval mode were in play if they matter.+ placeholder: |+ 1. …+ 2. …+ 3. …+ validations:+ required: true++ - type: input+ id: version+ attributes:+ label: Version+ description: Output of `penguin version`, or the version the app shows in System settings.+ placeholder: v0.2.7, or v0.2.7-14-g9e8f7d6-dirty for a source build+ validations:+ required: true++ - type: dropdown+ id: install+ attributes:+ label: How it is installed+ options:+ - Desktop app+ - CLI (penguin, from npm or an installer bundle)+ - Server (penguin server / penguin web)+ - From a source checkout (pnpm dev)+ validations:+ required: true++ - type: input+ id: os+ attributes:+ label: Operating system+ placeholder: macOS 15.4 (Apple silicon) / Windows 11 / Ubuntu 24.04+ validations:+ required: true++ - type: dropdown+ id: fresh-root+ attributes:+ label: Does it reproduce on a fresh data root?+ description: Run it once against an empty root — `PENGUIN_HOME=/tmp/penguin-check penguin ...`, or `--root` where the subcommand takes it. That separates a defect in the code from state an earlier version left behind, and it is the single most useful thing a report can say.+ options:+ - Yes — an empty data root still shows it+ - No — only my existing data root shows it+ - Not tested+ validations:+ required: true++ - type: textarea+ id: output+ attributes:+ label: Relevant output+ description: Error messages, the failing part of a log, or a screenshot. Redact keys and tokens before pasting.+ render: text+ validations:+ required: falsediff --git a/.github/ISSUE_TEMPLATE/config.yml b/.github/ISSUE_TEMPLATE/config.ymlnew file mode 100644index 00000000..53bbf3dd--- /dev/null+++ b/.github/ISSUE_TEMPLATE/config.yml@@ -0,0 +1,11 @@+blank_issues_enabled: false+contact_links:+ - name: Questions and usage help+ url: https://discord.gg/eFHKqqcU3D+ about: Ask on Discord — the issue tracker is for defects and proposals.+ - name: Documentation+ url: https://penguin.ooo/docs/+ about: Installation, configuration, the CLI reference, and the architecture.+ - name: Security vulnerability+ url: https://github.com/Prism-Shadow/penguin-harness/security/advisories/new+ about: Report privately. Never in a public issue.diff --git a/.github/ISSUE_TEMPLATE/feature_request.yml b/.github/ISSUE_TEMPLATE/feature_request.ymlnew file mode 100644index 00000000..63cffb63--- /dev/null+++ b/.github/ISSUE_TEMPLATE/feature_request.yml@@ -0,0 +1,32 @@+name: Feature request+description: Propose something PenguinHarness should be able to do.+labels: ["enhancement"]+body:+ - type: markdown+ attributes:+ value: |+ Please search the open issues first — and note that questions and usage help belong on [Discord](https://discord.gg/eFHKqqcU3D) or in the WeChat group rather than here.++ - type: textarea+ id: problem+ attributes:+ label: The problem+ description: What you were trying to do, and where PenguinHarness got in the way. Describe the situation rather than the fix — a concrete case is worth more than a feature name.+ validations:+ required: true++ - type: textarea+ id: proposal+ attributes:+ label: What you would like it to do+ description: The behavior you want, and where it would live — the Web App, the CLI, the SDK, a Skill, the model catalog.+ validations:+ required: true++ - type: textarea+ id: alternatives+ attributes:+ label: What you do instead today+ description: The workaround you are using, or why none of the existing surfaces covers it.+ validations:+ required: falsediff --git a/.github/PULL_REQUEST_TEMPLATE.md b/.github/PULL_REQUEST_TEMPLATE.mdnew file mode 100644index 00000000..eabe7032--- /dev/null+++ b/.github/PULL_REQUEST_TEMPLATE.md@@ -0,0 +1,21 @@+## What this changes++<!--+One or two sentences on what the change does and why it was needed. English, the+repository's working language. Add `Closes <full issue URL>` if it answers a report — a+bare `#N` is ambiguous here, because issues and pull requests share one numbering space.+-->++## Verification++<!--+What you ran, and what it said. Pick the narrowest evidence that would have failed without+this change; the full chain CI runs is `pnpm build`, `pnpm format:check`, `pnpm typecheck`,+`pnpm test`, `sh scripts/test-installer.sh`, on Node >= 24.+-->++## Checklist++- [ ] Changelog entry pair under `changelog/unreleased/` — `YYYY-MM-DD-<slug>.md` and its `.zh.md` counterpart, in the format [changelog/README.md](https://github.com/Prism-Shadow/penguin-harness/blob/main/changelog/README.md) describes.+- [ ] Docs updated where this changes documented behavior (README, `packages/docs/content/`).+- [ ] No API key, bot token or other credential in the diff, the logs, or the screenshots.diff --git a/.github/SECURITY.md b/.github/SECURITY.mdnew file mode 100644index 00000000..2f0e1522--- /dev/null+++ b/.github/SECURITY.md@@ -0,0 +1,75 @@+# Security Policy++[中文版](https://github.com/Prism-Shadow/penguin-harness/blob/main/.github/SECURITY.zh.md)++## Supported versions++PenguinHarness is pre-1.0 and ships from `main`. There are no maintenance branches and+nothing is backported: a fix lands in the next release, and upgrading is the way to get it.++| Version | Supported |+| ----------------------- | --------- |+| The most recent release | Yes |+| Any earlier release | No |++The releases are listed in+[CHANGELOG.md](https://github.com/Prism-Shadow/penguin-harness/blob/main/CHANGELOG.md);+`penguin version` prints which build a machine is actually running.++## Reporting a vulnerability++Report privately, through GitHub's+["Report a vulnerability"](https://github.com/Prism-Shadow/penguin-harness/security/advisories/new)+form. It opens a draft advisory only the maintainers can see, and it keeps the discussion,+the fix and the eventual disclosure attached to one another.++If that form is unavailable to you, mail <[email protected]>. Do not open a public issue,+a discussion, or a pull request for a security problem, and do not post it to Discord or the+WeChat group — those are public.++A report is most useful with the affected version, how PenguinHarness was installed+(desktop app, CLI, or a server run), the operating system, and the smallest sequence of+steps that reproduces the problem. **Strip credentials before you send anything.** A data+root holds provider API keys, messaging bot tokens and Vault entries in readable form, so a+`system_config.yaml`, a `.env`, a Trace or a full log is very likely to carry a secret;+quote the few lines that matter instead of attaching the file.++You will get an acknowledgement of the report and, once someone has looked at it, an+assessment of what it affects and what happens next. This is a small team, so expect days+rather than hours, and expect to be asked for more detail.++## What counts++PenguinHarness runs an agent on your own machine, and that agent runs shell commands, reads+and writes files, and talks to model providers with credentials you configured. Within that+design, these are in scope:++- Anything that lets a Session act outside the boundary the running approval mode+ established — an approval prompt bypassed or spoofed, a `[command_policy]` deny rule+ evaded through a spelling it should have matched.+- Credential exposure: an API key, a bot token or a Vault entry reaching a log, a Trace, an+ error page, an LLM request, or another user's view of the server.+- Anything crossing the multi-user boundary in the server — one account reaching another+ account's Projects, Sessions, Workspaces or usage data, authentication or session-token+ handling that can be defeated, or authorization missing on an API route.+- Remote input that gets to act: a web page, a file, an MCP server or an inbound chat+ message whose content is treated as instructions in a way the user could not see coming,+ or that reaches a tool without passing the approval boundary at all.+- The installers and the update path: an install or `penguin update` that can be redirected+ to code the project did not publish.++These are not, because they are the documented design rather than a defect:++- An agent doing what a tool call you approved permits, including destructive commands under+ `allow-all`.+- The `[command_policy]` sandbox failing to stop a command it never claimed to cover. It is+ documented as a deny-list at the approval boundary and explicitly not a filesystem+ permission or a confinement layer — see+ [Configuration → Command policy](https://penguin.ooo/docs/configuration). Real confinement+ (bubblewrap, dsh) is a separate layer.+- A server deliberately exposed to a network it should not be on. PenguinHarness binds to+ `127.0.0.1` by default; putting it on a public address is a deployment decision.+- Secrets readable on disk by someone who already has your user account or your data root.+- Vulnerabilities in a model provider, an MCP server, or another third-party dependency —+ report those to whoever maintains them. If a dependency's flaw is reachable through+ PenguinHarness in a way its own maintainers would not consider a bug, tell us as well.diff --git a/.github/SECURITY.zh.md b/.github/SECURITY.zh.mdnew file mode 100644index 00000000..63f3a9be--- /dev/null+++ b/.github/SECURITY.zh.md@@ -0,0 +1,60 @@+# 安全策略++[English](SECURITY.md)++## 支持的版本++PenguinHarness 尚未发布 1.0,代码从 `main` 出货。项目没有维护分支,也不做回移植:修复进入下一个版本,+拿到修复的方式就是升级。++| 版本 | 是否支持 |+| -------------- | -------- |+| 最新发布版本 | 是 |+| 更早的任何版本 | 否 |++历次发布见 [CHANGELOG.zh.md](../CHANGELOG.zh.md);`penguin version` 会打印某台机器实际运行的是哪个+构建。++## 报告漏洞++请通过 GitHub 的+["Report a vulnerability"](https://github.com/Prism-Shadow/penguin-harness/security/advisories/new)+表单私下报告。它会创建一份只有维护者可见的 advisory 草稿,讨论、修复与最终披露都挂在同一处。++如果你无法使用该表单,请发邮件至 <[email protected]>。不要为安全问题开公开 issue、discussion 或+Pull Request,也不要发到 Discord 或微信群——那些都是公开场合。++一份报告最有用的内容是:受影响的版本、PenguinHarness 的安装方式(桌面应用、CLI,还是自行运行的+server)、操作系统,以及能复现问题的最短步骤。**发送前请先剔除凭据。** 数据根目录中的 Provider API+Key、消息机器人 Token 与 Vault 条目都以可读形式存放,因此 `system_config.yaml`、`.env`、Trace 或完整+日志极有可能夹带密钥;请只摘录真正相关的那几行,而不要整份附上。++你会先收到一封确认回执;待有人看过之后,会收到关于影响范围与后续处理的判断。这是一个小团队,时间尺度+以天计而非以小时计,并且很可能会追问更多细节。++## 什么算漏洞++PenguinHarness 在你自己的机器上运行 Agent,而这个 Agent 会执行 shell 命令、读写文件,并带着你配置的+凭据访问模型 Provider。在这一设计之内,以下属于范围内:++- 任何使 Session 越过当前审批模式所划定边界的行为——绕过或伪造审批提示,或以本应被匹配到的写法规避+ `[command_policy]` 的 deny 规则。+- 凭据泄露:API Key、机器人 Token 或 Vault 条目出现在日志、Trace、错误页、LLM 请求,或另一名用户的+ 视图中。+- 任何越过 server 多用户边界的行为——某个账号触及另一账号的 Project、Session、Workspace 或用量数据,+ 认证与会话 Token 处理可被攻破,或某个 API 路由缺少鉴权。+- 能够动手的远端输入:网页、文件、MCP Server 或入站聊天消息中的内容,以用户无法预见的方式被当作指令+ 执行,或根本没有经过审批边界就抵达了工具。+- 安装器与更新路径:安装过程或 `penguin update` 可被引导去获取并非本项目发布的代码。++以下不属于,因为它们是既定设计而非缺陷:++- Agent 在你已批准的工具调用允许范围内所做的事,包括 `allow-all` 模式下的破坏性命令。+- `[command_policy]` 沙箱没能拦住它从未声称覆盖的命令。文档中它被定义为审批边界上的一份 deny 列表,+ 并明确说明它不是文件系统权限,也不是隔离层——见+ [配置 → 命令策略](https://penguin.ooo/docs/configuration)。真正的隔离(bubblewrap、dsh)是另一层。+- 有意暴露到不该暴露的网络上的 server。PenguinHarness 默认绑定 `127.0.0.1`,把它放到公网地址上是一项+ 部署决定。+- 已经拿到你的用户账号或数据根目录的人能够读到磁盘上的密钥。+- 模型 Provider、MCP Server 或其他第三方依赖自身的漏洞——请报告给它们各自的维护者。如果某个依赖的缺陷+ 能通过 PenguinHarness 以其维护者不会视为 bug 的方式被利用,也请一并告知我们。diff --git a/.github/workflows/release.yml b/.github/workflows/release.ymlindex 28280b9e..adb181b5 100644--- a/.github/workflows/release.yml+++ b/.github/workflows/release.yml@@ -144,7 +144,7 @@ jobs:if [ -f package.json ]; thenPKG_V="$(node -p 'require("./package.json").version')"if [ "$PKG_V" != "$V" ]; then- MSG="tag $TAG does not match the repo version $PKG_V; bump root + packages/*/package.json and core VERSION during release prep, then re-tag (see CONTRIBUTING.md)."+ MSG="tag $TAG does not match the repo version $PKG_V; bump root + packages/*/package.json and core VERSION during release prep, then re-tag (see .github/CONTRIBUTING.md)."if [ "${EVENT_NAME:-}" = "push" ]; thenecho "error: $MSG" >&2exit 1@@ -593,7 +593,7 @@ jobs:if [ -f package.json ]; thenPKG_V="$(node -p 'require("./package.json").version')"if [ "$PKG_V" != "$V" ]; then- MSG="tag $TAG does not match the repo version $PKG_V; bump root + packages/*/package.json and core VERSION during release prep, then re-tag (see CONTRIBUTING.md)."+ MSG="tag $TAG does not match the repo version $PKG_V; bump root + packages/*/package.json and core VERSION during release prep, then re-tag (see .github/CONTRIBUTING.md)."if [ "${EVENT_NAME:-}" = "push" ]; thenecho "error: $MSG" >&2exit 1diff --git a/README.md b/README.mdindex 060cbb1b..2bf9f917 100644--- a/README.md+++ b/README.md@@ -248,7 +248,7 @@ pnpm install && pnpm build # build first: core's exports point at dist/pnpm dev # backend + web app together (prefixed logs, deps built once)```-See [CONTRIBUTING.md](CONTRIBUTING.md) for the full workspace guide: dev commands, quality gates, repo layout, and the changelog rule.+See [CONTRIBUTING.md](.github/CONTRIBUTING.md) for the full workspace guide: dev commands, quality gates, repo layout, and the changelog rule.## Contributorsdiff --git a/README.zh.md b/README.zh.mdindex 2284770f..72ef761a 100644--- a/README.zh.md+++ b/README.zh.md@@ -248,7 +248,7 @@ pnpm install && pnpm build # 先构建:core 的导出指向 dist/pnpm dev # 服务端 + Web 一起启动(带前缀日志,依赖只构建一次)```-完整工作区指南见 [CONTRIBUTING.md](CONTRIBUTING.md):开发命令、质量门禁、仓库结构与 changelog 规则。+完整工作区指南见 [CONTRIBUTING.zh.md](.github/CONTRIBUTING.zh.md):开发命令、质量门禁、仓库结构与 changelog 规则。## 贡献者diff --git a/changelog/unreleased/2026-08-27-community-standards.md b/changelog/unreleased/2026-08-27-community-standards.mdnew file mode 100644index 00000000..42d2bb27--- /dev/null+++ b/changelog/unreleased/2026-08-27-community-standards.md@@ -0,0 +1,46 @@+# The community health files GitHub looks for, all under .github/++- **Date:** 2026-08-27+- **Type:** process+- **Scope:** `docs`, `tooling`+- **PR:** [#514](https://github.com/Prism-Shadow/penguin-harness/pull/514)++[中文版](2026-08-27-community-standards.zh.md)++GitHub's Community Standards page listed five unchecked entries — code of conduct,+contributing, security policy, issue templates, pull request template. All five were+written, and every file GitHub recognizes from inside `.github/` was placed there, so no+new file was added at the repository root.++## Details++- `CONTRIBUTING.md` **moved** from the root to `.github/CONTRIBUTING.md` (a rename, not a+ copy) with its content intact and its repo-relative links re-anchored one level up. It+ gained a Code of Conduct and security-policy pointer at the top, a section on filing a+ bug or a feature request, and a pull-request bullet naming the English title, the+ `## Verification` section and the template. The four references to it — in `README.md`,+ `README.zh.md`, `.github/workflows/release.yml` and the `penguin-harness-dev` skill —+ were repointed at the new path.+- `.github/CODE_OF_CONDUCT.md` was added as the Contributor Covenant 2.1 verbatim, with+ <[email protected]> filled in as the enforcement contact, and its Chinese counterpart+ took the Covenant's own zh-cn translation. Neither file was written as a paraphrase, so a+ later version bump stays a clean diff against upstream.+- `.github/SECURITY.md` was written to route reports to GitHub's private "Report a+ vulnerability" form, with the maintainer's address as the fallback, and to state that+ only the most recent release is supported — the project is pre-1.0, ships from `main`,+ and backports nothing. It also drew the scope line the product needs: an approval+ bypass, a `[command_policy]` evasion, a credential reaching a log or a Trace, and a+ break in the server's multi-user boundary are in scope, while an agent doing what an+ approved tool call permits is the documented design.+- `.github/ISSUE_TEMPLATE/` gained `bug_report.yml` and `feature_request.yml` as form+ schemas, plus a `config.yml` that turns off blank issues and links Discord, the docs and+ the security advisory form. The bug form asks for the version (`penguin version`), the+ install shape, the OS, and whether the problem survives a fresh data root; both forms and+ the contributor guide state plainly that a config file, a `.env` or a full log is likely+ to carry a provider key or a bot token and does not belong in a public issue.+- `.github/PULL_REQUEST_TEMPLATE.md` was added, asking for what changed, a+ `## Verification` section naming what was run, and a changelog entry pair under+ `changelog/unreleased/`.+- The two documents a reporter or a newcomer reads rather than a maintainer — the Code of+ Conduct and the security policy — shipped with `.zh.md` counterparts, as did the+ contributor guide. The GitHub-rendered templates did not.diff --git a/changelog/unreleased/2026-08-27-community-standards.zh.md b/changelog/unreleased/2026-08-27-community-standards.zh.mdnew file mode 100644index 00000000..e3e70721--- /dev/null+++ b/changelog/unreleased/2026-08-27-community-standards.zh.md@@ -0,0 +1,36 @@+# GitHub 期待的社区健康文件,全部收进 .github/++- **Date:** 2026-08-27+- **Type:** process+- **Scope:** `docs`, `tooling`+- **PR:** [#514](https://github.com/Prism-Shadow/penguin-harness/pull/514)++[English](2026-08-27-community-standards.md)++GitHub 的 Community Standards 页面此前列出五项未勾选——行为准则、贡献指南、安全策略、issue 模板、+Pull Request 模板。五项全部补齐,且凡是 GitHub 能从 `.github/` 内识别的文件都放在了那里,因此仓库根+目录没有新增任何文件。++## 细节++- `CONTRIBUTING.md` 从根目录**移动**到 `.github/CONTRIBUTING.md`(是重命名,不是复制),内容原样保留,+ 仓库内相对链接上移一级重新锚定。文件顶部新增了指向行为准则与安全策略的指引,新增了一节讲如何提交+ 缺陷报告或功能建议,并在 Pull Request 一节补上一条:标题用英文、`## Verification` 小节、以及模板。+ 指向它的四处引用——`README.md`、`README.zh.md`、`.github/workflows/release.yml` 与+ `penguin-harness-dev` skill——都已改指新路径。+- 新增 `.github/CODE_OF_CONDUCT.md`,采用 Contributor Covenant 2.1 原文,执行联系方式填为+ <[email protected]>;其中文对应文件采用了该公约官方的 zh-cn 译本。两份文件都不是转述,日后升级+ 版本时也就是一份干净的上游 diff。+- 新增 `.github/SECURITY.md`,把报告导向 GitHub 私密的 "Report a vulnerability" 表单,并以维护者邮箱+ 作为兜底;同时说明只有最新发布版本受支持——项目尚未 1.0,代码从 `main` 出货,不做任何回移植。它还+ 划出了这个产品需要的范围线:绕过审批、规避 `[command_policy]`、凭据落入日志或 Trace、以及 server+ 多用户边界被击穿属于范围内,而 Agent 在已批准的工具调用允许范围内所做的事属于既定设计。+- `.github/ISSUE_TEMPLATE/` 新增了 `bug_report.yml` 与 `feature_request.yml` 两份表单 schema,外加+ 一份 `config.yml`:关闭空白 issue,并链接 Discord、文档站与安全 advisory 表单。缺陷表单会索取版本+ (`penguin version`)、安装形态、操作系统,以及问题是否在全新数据根目录上依然出现;两份表单与贡献+ 指南都明确写出:配置文件、`.env` 或完整日志极可能夹带 Provider Key 或机器人 Token,不该出现在公开+ issue 里。+- 新增 `.github/PULL_REQUEST_TEMPLATE.md`,索取改动内容、一个写明实际运行了什么的 `## Verification`+ 小节,以及 `changelog/unreleased/` 下的中英成对 changelog 条目。+- 由报告者或新人(而非维护者)阅读的两份文档——行为准则与安全策略——都随附了 `.zh.md` 对应文件,贡献+ 指南同样如此。由 GitHub 渲染的模板则没有。