VelaShell

Imported from joesdu/VelaShell (AGENTS.md). Install upstream with npx skills add joesdu/VelaShell. Copyright stays with the author.

AGENTS.md

给 AI 代理与新加入者的操作约定。动手之前先读完本文件,以及它指向的文档。

一、开工前必读:velashell-docs

VelaShell 生态的全部文档集中在一个仓库: VelaShellLabs/velashell-docs。 本仓库不放 docs/、docs-en/ —— 设计手册、开发规范与开发文档都在那边。

在动任何代码之前,先把下表中与你要改的部分相关的几篇读掉。跳过这一步直接改, 结果通常是两种:与既有设计冲突,或者重复实现一个已经存在的能力。

英文镜像在 en/,与 zh/ 同构。 仓库首页有按「我想做什么」组织的快速入口表。

二、涉及文档的改动一律同步到 velashell-docs

这是本文件最重要的一条。

• 本仓库里不新建 docs/、docs-en/ 或任何成体系的文档目录。要写文档,去 velashell-docs 开 PR。
• 改了代码,而行为、接口、配置项、命令行、构建流程或版本纪律与现有文档对不上时, 必须同时在 velashell-docs 提一个 PR 把文档改过来。两个 PR 在正文里互相引用,一起合。 只改代码不改文档,等于让文档开始骗人 —— 而文档是别人照抄的。
• velashell-docs 的 zh/ 与 en/ 是互为镜像的两棵树,文件一一对应。改了中文就要改英文, 反之亦然。漏一边,两棵树就开始漂。
• velashell-docs 内部的互相引用一律走相对路径(如 ../templates/dev-guide.md), 不要写回 GitHub 绝对 URL —— 文档集中到一个仓库,消掉的正是那种一改路径就断的跨仓库链接。
• 例外:留在代码仓库里的少数几份文件不适用上述规则,因为它们服务的是「在这个仓库里写代码」 这件事,搬走只会离使用场景更远。各仓库的例外清单见下面第三节。

三、本仓库:VelaShell(宿主主程序)

.NET 11 + Avalonia 12.1 的跨平台终端客户端,以及宿主侧的插件运行时。

构建与测试

dotnet build VelaShell.slnx
dotnet test  VelaShell.slnx

留在本仓库的文档(不搬去 velashell-docs)

改 UI 相关代码前先读 DESIGN.md:XAML 与 C# 里不许出现颜色字面量,一律用 DynamicResource 绑定令牌。

几条会让你踩坑的硬约束

• 界面文案五份 resx 必须齐(Strings / zh-Hans / zh-Hant / ja / ko),不许硬编码字符串。 漏译与孤儿键由 LocalizedKeyUsageTests / UnusedLocalizedKeyTests 拦住。
• 新增或改动快捷键先改目录:唯一事实来源是 src/VelaShell/ViewModels/ShortcutCatalog.cs,设置页与文档都从它取数。没登记的话 ShortcutCatalogTests 会失败并打印出可粘贴的 Markdown 行。快捷键文档在 zh/host/快捷键参考.md,改了要同步。
• 集成测试按环境早退跳过,而 MSTest 把跳过记为「通过」。DockerIntegration 分类需要 Docker 与 docker-compose.test.yml,CrossPlatformPublishTests 需 VELASHELL_PUBLISH_TESTS=1。 要确认它们真跑过,看 TestContext 里有没有 [SKIP] 行 —— 全绿不等于跑过。
• headless UI 测试要用带返回值的重载:Dispatch(async () => { …; return true; })。 HeadlessUnitTestSession 没有 Func<Task> 重载,写成无返回值会拿到一个从未被等待的 Task<Task>,测试跑到第一个 await 就"通过",断言失败全部丢失。
• 插件 SDK 一律走 NuGet 包,不做工程引用。版本在 src/Directory.Packages.props。
• 不要自己决定 SDK 版本号,也不要造本地包。宿主的改动需要 SDK 的新契约时,正确做法是: 在 velashell-plugin-sdk 里把契约写好(那边同样不动版本号),然后明确交代 「需要发一版 SDK,发完把 src/Directory.Packages.props 与 tests/Directory.Packages.props 抬上去」。在那之前宿主编译不过是预期内的,不是要绕过的障碍。 绝不要 dotnet pack 一个本地包、往 nuget.config 塞本地源、或者把包版本指到一个 还不存在的号 —— 下一版发什么号是排期决定的,你猜一个就把所有下游都钉死在那个号上了; 何况本地包未签名(VelaShell.snk 不在仓库里),一编译就是一片 CS0012 假错误。
• 永远不要试图使用Python来执行脚本或者进行什么操作.可以使用PowerShell或C#的单文件脚本的方式来处理.可以参考文档: https://learn.microsoft.com/zh-cn/dotnet/core/sdk/file-based-apps

相关仓库

插件契约 SDK、vela-plugin CLI、dotnet new 模板、第一方插件与插件商店都在 VelaShellLabs 组织下,文档全部在 velashell-docs。

提交约束

• 所有提交信息与 PR 描述都不要附加 Claude Code 等 AI 工具的作者信息 —— 不加 Co-Authored-By: Claude … 行,也不加 🤖 Generated with Claude Code 之类的署名。VelaShellLabs 下所有仓库一致适用。
• 只有仓库所有者才需要从dev分支发 PR,其他人都从 feature 分支发 PR。feature 分支的命名规则是 feat/xxx 或 fix/xxx,其中 xxx 是简短描述,不许用中文。
• 创建PR的时候直接选择合并到main分支,但是在PR描述中必须写明本次PR的主要改动内容,以及是否涉及到文档的修改,如果涉及到文档的修改,请在PR描述中附上对应的文档链接。