Skip to content

Commit efd9bb3

Browse files
juice094juice094
committed
feat: expand developer skills and repository guidance
- Add built-in developer Skills and strengthen prompt capability boundaries. - Document UI rollout and improve bilingual project and community guidance. - Add Skill discovery coverage and GitHub contribution templates.
1 parent 2c2d3a3 commit efd9bb3

32 files changed

Lines changed: 680 additions & 10 deletions

‎.codex/skills/ui-ux-development/SKILL.md‎

Lines changed: 30 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,30 @@
1+
---
2+
name: ui-ux-development
3+
description: 按 webcode 已批准的 UI 体验开发计划执行界面基线、可访问性审计、单流程设计令牌试点和分步推广。用于修改浏览器 popup、注入 overlay/modal 或 VS Code UI 的请求；Rust 暂缓，不得自行扩展为框架迁移或全量视觉重做。
4+
---
5+
6+
# webcode UI/UX 开发
7+
8+
开始任何 UI 相关实现前，先阅读 [UI 开发计划](../../../doc/UI_UX_DEVELOPMENT_PLAN.md)，并按以下流程执行。
9+
10+
## 工作流
11+
12+
1. **确认 surface 和路径。** 明确改动属于 VS Code 原生控件、浏览器 popup 还是注入 overlay/modal；列出受影响的核心任务、宿主主题、键盘与屏幕阅读器需求。信息缺失时标记“待确认”，不要假设用户痛点或使用数据。
13+
2. **先建基线。** 记录可复现步骤、完成率/耗时/点击输入数（若可采集）、焦点路径、对比度和反馈延迟。注明环境、版本、样本量和方法；没有基线就不得声称改善或性能回归。
14+
3. **限定单流程改动。** 首选现有 HTML、TypeScript、VS Code API 和 CSS 变量/语义令牌；不引入 React、Vue、大型组件库、Rust/N-API/WASM，不做全量重写。VS Code UI 遵循宿主主题。不要顺手更改审批、安全、桥接协议或自动发送语义。
15+
4. **把可访问性作为硬门槛。** 核心流程必须可键盘完成，焦点清晰可见，文本/控件满足 WCAG 2.2 AA 对比度，严重级 a11y 问题为 0。弹窗应检查焦点进入、退出与恢复；动效尊重 `prefers-reduced-motion`。
16+
5. **比较性能。** 用相同环境对照基线与变更，测量反馈延迟、UI 长任务和相关首屏/状态呈现时间。性能回退阈值须在试点前由负责人批准；阈值未给出时标记待确认，不得擅自用某个百分比代替。
17+
6. **运行范围适当的验证。** 运行相关单元测试、`pnpm lint`，以及受影响的包构建/测试；浏览器流程按需要运行 `pnpm test:e2e:minimal`。确定性 E2E 不代表真实 UI 已验收。
18+
7. **交互式 QA 需要授权。** 不因收到实现请求就启动浏览器。只有用户明确授权后，才能按 `webcode-browser-qa` Skill 使用 `qa:start` 创建的隔离工作区/配置；完成后运行 `qa:stop`。
19+
8. **提交证据与回滚。** 汇报改动 surface、测量方法与结果、a11y 检查、测试、未覆盖风险和回滚方式。试点应可独立 revert；未验证的内容写明“未验证”。
20+
21+
## Rust 决策边界
22+
23+
Rust 不进入近期 UI 计划，不安排 PoC/试点，不改变构建或发布矩阵。只有 UI 计划附录列出的触发条件成立后，才可提出重新评估；必须由具备互操作审查和生产兜底能力的负责人批准。AI 辅助开发不替代最终审查、调试与故障定位。
24+
25+
## 完成条件
26+
27+
- 变更限于获批的单流程或阶段范围。
28+
- 硬性键盘、焦点、WCAG 2.2 AA 对比度与严重问题门槛通过。
29+
- 性能未超过试点前已批准的回退阈值；没有阈值时不得宣称性能验收通过。
30+
- 有对应测试和可执行回滚；测试或交互流程未运行时明确披露。

‎.github/ISSUE_TEMPLATE/bug_report.yml‎

Lines changed: 52 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,52 @@
1+
name: 问题报告 / Bug report
2+
description: 报告可复现的缺陷 / Report a reproducible defect
3+
title: "bug: "
4+
body:
5+
- type: markdown
6+
attributes:
7+
value: |
8+
请先搜索已有 Issue。安全漏洞请勿通过公开表单披露，参见 [SECURITY.md](https://github.com/three-water666/webcode/blob/main/SECURITY.md)。
9+
- type: textarea
10+
id: summary
11+
attributes:
12+
label: 问题描述 / Summary
13+
description: 简洁说明发生了什么。
14+
validations:
15+
required: true
16+
- type: textarea
17+
id: reproduction
18+
attributes:
19+
label: 复现步骤 / Steps to reproduce
20+
description: 提供最小、可重复的步骤。
21+
placeholder: |
22+
1. ...
23+
2. ...
24+
3. ...
25+
validations:
26+
required: true
27+
- type: textarea
28+
id: expected-actual
29+
attributes:
30+
label: 预期与实际结果 / Expected and actual behavior
31+
validations:
32+
required: true
33+
- type: input
34+
id: webcode-version
35+
attributes:
36+
label: webcode 版本 / Version
37+
validations:
38+
required: true
39+
- type: input
40+
id: environment
41+
attributes:
42+
label: 环境 / Environment
43+
description: OS、VS Code 版本、浏览器及相关 AI 站点。
44+
validations:
45+
required: true
46+
- type: textarea
47+
id: logs
48+
attributes:
49+
label: 日志或截图 / Logs or screenshots
50+
description: 请先移除令牌、个人数据和其他敏感信息。
51+
validations:
52+
required: false

‎.github/ISSUE_TEMPLATE/feature_request.yml‎

Lines changed: 29 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,29 @@
1+
name: 功能建议 / Feature request
2+
description: 提出功能或改进建议 / Suggest a feature or improvement
3+
title: "feat: "
4+
body:
5+
- type: markdown
6+
attributes:
7+
value: |
8+
请先搜索已有 Issue，确认没有重复建议。
9+
- type: textarea
10+
id: problem
11+
attributes:
12+
label: 要解决的问题 / Problem
13+
description: 描述当前遇到的限制或需求。
14+
validations:
15+
required: true
16+
- type: textarea
17+
id: proposal
18+
attributes:
19+
label: 建议方案 / Proposed solution
20+
description: 描述期望的行为；如有替代方案也请说明。
21+
validations:
22+
required: true
23+
- type: textarea
24+
id: context
25+
attributes:
26+
label: 使用场景 / Use case
27+
description: 谁会使用此功能，以及它如何帮助完成任务？
28+
validations:
29+
required: true

‎.github/pull_request_template.md‎

Lines changed: 15 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,15 @@
1+
# Pull Request
2+
3+
## 改动说明
4+
5+
<!-- 描述问题背景、改动内容和用户可见影响。 -->
6+
7+
## 验证
8+
9+
- [ ] 已运行适用的构建、测试或 lint
10+
- [ ] 已更新受影响的文档
11+
- [ ] 未提交密钥、个人数据或本地运行产物
12+
13+
验证结果或未运行项目：
14+
15+
<!-- 说明命令和结果；如有未运行的检查，请写明原因。 -->

‎CHANGELOG.md‎

Lines changed: 10 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,10 @@
1+
# 变更记录
2+
3+
项目双语版本记录按版本保存在以下目录：
4+
5+
- [中文版本记录](changelogs/zh/)
6+
- [English release notes](changelogs/en/)
7+
- [最新版本 v1.2.1（中文）](changelogs/zh/v1.2.1.md)
8+
- [Latest release v1.2.1 (English)](changelogs/en/v1.2.1.md)
9+
10+
VS Code 扩展包内的变更记录见 [gateway-vscode/CHANGELOG.md](gateway-vscode/CHANGELOG.md)。

‎CODE_OF_CONDUCT.md‎

Lines changed: 13 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,13 @@
1+
# 行为准则（待确认草案）
2+
3+
> 本文件尚未由维护者正式采纳。请在公布为正式社区政策前确认行为标准、执行流程和报告渠道。
4+
5+
## 建议的社区标准
6+
7+
- 以尊重、善意和建设性的方式参与讨论与协作。
8+
- 聚焦问题和技术事实，不进行人身攻击、骚扰或歧视性表达。
9+
- 尊重他人的隐私；未经许可不公开个人信息或私下通信内容。
10+
11+
## 执行与报告
12+
13+
**待确认：** 负责处理行为准则报告的维护者、私密报告渠道、处理流程及适用措施尚未明确。确认前，不应将本草案描述为已经生效的政策。

‎CONTRIBUTING.md‎

Lines changed: 39 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,39 @@
1+
# 贡献指南
2+
3+
感谢你愿意为 webcode 提交问题或改进。提交前请先搜索已有 Issue 和 Pull Request，避免重复工作。
4+
5+
## 开发环境
6+
7+
- Node.js 22
8+
- pnpm 10.25.0
9+
- VS Code 1.106.1 或更新版本（运行扩展宿主测试时需要）
10+
11+
在仓库根目录安装依赖并构建共享包：
12+
13+
```bash
14+
pnpm install
15+
pnpm --filter @webcode/shared run build
16+
```
17+
18+
## 提交前检查
19+
20+
```bash
21+
pnpm build
22+
pnpm test
23+
pnpm test:extension
24+
pnpm lint
25+
```
26+
27+
浏览器端到端测试和交互式 QA 需要额外的浏览器环境，运行方式见 [Evals 指南](evals/README.md)。只有在受影响的流程需要时再执行；交互式 QA 必须使用 `qa:start` 创建的隔离工作区。
28+
29+
## Pull Request
30+
31+
- 说明问题背景、预期行为和实际改动；涉及 UI 或用户流程时附上复现步骤或截图。
32+
- 为行为变化补充或更新测试，并同步维护相关的中英文用户文档。
33+
- 不提交密钥、账号数据、浏览器 profile 或 `evals/runs/` 等本地运行产物。
34+
- 使用简洁的 Conventional Commit 标题。较大改动的正文描述行为变化，不记录常规测试命令输出。
35+
- 详细提交规范见 [AGENTS.md](AGENTS.md)。
36+
37+
## 文档
38+
39+
用户文档位于仓库根目录和 `doc/`；浏览器插件说明位于 `bridge-browser/`；评测说明位于 `evals/`。Marketplace README 由根目录的中英文 README 生成，不要直接编辑生成文件。

‎README.md‎

Lines changed: 51 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -32,6 +32,27 @@
3232
<img src="doc/assets/webcode-usage-screenshot.png" width="960" alt="webcode 使用截图">
3333
</p>
3434

35+
## 项目能力
36+
37+
- 在网页 AI 对话中调用本地文件、搜索和命令工具，并在需要时请求用户审批。
38+
- 通过 VS Code 扩展和浏览器 bridge 建立本地 Gateway 连接。
39+
- 接入第三方 MCP server，并向网页 AI 提供工作区 Skills。
40+
- 支持多个内置 AI 站点，也可通过 VS Code 设置添加或覆盖站点。
41+
42+
## 文档导航
43+
44+
| 主题 | 文档 |
45+
| ------ | ------ |
46+
| 构建、开发和功能指南 | [文档目录](doc/README.md) |
47+
| 浏览器模式 | [浏览器模式指南](doc/BROWSER_MODE_GUIDE.md) |
48+
| 内置工具 | [内置工具说明](doc/BUILTIN_TOOLS.md) |
49+
| MCP 配置 | [MCP 服务配置指南](doc/MCP_GUIDE.md) |
50+
| 站点扩展 | [站点支持指南](doc/PLATFORM_GUIDE.md) |
51+
| 常见问题 | [FAQ](doc/FAQ_GUIDE.md) |
52+
| 开发与贡献 | [贡献指南](CONTRIBUTING.md) |
53+
54+
语言版本：[English](README_en.md)。
55+
3556
## 使用示例
3657

3758
### DeepSeek 网页版：鹈鹕测试
@@ -54,7 +75,7 @@ https://github.com/user-attachments/assets/448873b4-922a-4cac-b421-70a189394576
5475

5576
[查看 SVG 源文件](doc/assets/pelican-bicycle-deepseek.svg)
5677

57-
## 快速开始
78+
## 安装与快速开始
5879

5980
### 1. 安装 VS Code 扩展
6081

@@ -126,6 +147,10 @@ webcode 可以把当前 VS Code 工作区中的本地 Skills 暴露给网页 AI
126147

127148
如果 `AGENTS.md` 和 `CLAUDE.md` 同时存在，只发送 `AGENTS.md`。浏览器扩展不再提供单独的个性化指令设置页。
128149

150+
## 配置
151+
152+
VS Code 设置使用 `webcodeGateway.*` 命名空间。站点配置见[站点支持指南](doc/PLATFORM_GUIDE.md)，MCP server 配置见[MCP 指南](doc/MCP_GUIDE.md)，浏览器选择见[浏览器模式指南](doc/BROWSER_MODE_GUIDE.md)。
153+
129154
## 目前已内置支持的 AI 平台及其他平台支持
130155

131156
webcode 目前已内置支持以下 AI 平台：
@@ -150,14 +175,37 @@ webcode 目前已内置支持以下 AI 平台：
150175

151176
首次启动环境、触发词无反应、工具调用执行后页面没有变化、查看历史工具调用等问题见 [常见问题](doc/FAQ_GUIDE.md)。
152177

178+
## 项目结构
179+
180+
- `gateway-vscode/`：VS Code 扩展、Gateway、MCP 和本地工具。
181+
- `bridge-browser/`：浏览器扩展及页面桥接逻辑。
182+
- `shared/`：跨包共享类型和逻辑。
183+
- `evals/`：单元评测、端到端场景和 QA 脚本。
184+
- `doc/`：使用、构建和开发指南。
185+
186+
## 开发与测试
187+
188+
需要 Node.js 22 和 pnpm 10.25.0。克隆仓库后，在根目录运行：
189+
190+
```bash
191+
pnpm install
192+
pnpm --filter @webcode/shared run build
193+
pnpm build
194+
pnpm test
195+
pnpm test:extension
196+
pnpm lint
197+
```
198+
199+
各命令的范围及浏览器端到端测试说明见[构建指南](doc/BUILD_GUIDE.md)和[文档目录](doc/README.md)。
200+
153201
## 参与贡献
154202

155-
欢迎提交 Issue 和 Pull Request。
203+
欢迎提交 Issue 和 Pull Request。提交前请阅读[贡献指南](CONTRIBUTING.md)；安全问题请参阅[安全策略](SECURITY.md)。行为准则目前仍待维护者确认，见[行为准则草案](CODE_OF_CONDUCT.md)。
156204

157205
## 致谢
158206

159207
感谢 [LINUX DO](https://linux.do/) 社区提供技术交流与开源分享的平台。
160208

161209
## 许可证
162210

163-
[MIT License](LICENSE)
211+
本仓库采用 MIT License，详见 [LICENSE](LICENSE)。

‎README_en.md‎

Lines changed: 51 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -32,6 +32,27 @@
3232
<img src="doc/assets/webcode-usage-screenshot.png" width="960" alt="webcode usage screenshot">
3333
</p>
3434

35+
## What webcode does
36+
37+
- Lets web AI use local file, search, and command tools, with user approval where required.
38+
- Connects a VS Code extension and browser bridge through a local Gateway.
39+
- Exposes third-party MCP servers and workspace Skills to web AI.
40+
- Supports built-in AI sites and user-defined site settings.
41+
42+
## Documentation
43+
44+
| Topic | Guide |
45+
| ------ | ------ |
46+
| Build, development, and feature guides | [Documentation index](doc/README_en.md) |
47+
| Browser modes | [Browser mode guide](doc/BROWSER_MODE_GUIDE_en.md) |
48+
| Built-in tools | [Built-in tools reference](doc/BUILTIN_TOOLS_en.md) |
49+
| MCP configuration | [MCP configuration guide](doc/MCP_GUIDE_en.md) |
50+
| Site support | [Site support guide](doc/PLATFORM_GUIDE_en.md) |
51+
| Troubleshooting | [FAQ](doc/FAQ_GUIDE_en.md) |
52+
| Development and contributions | [Contributing guide](CONTRIBUTING.md) |
53+
54+
Language versions: [中文](README.md).
55+
3556
## Examples
3657

3758
### DeepSeek Web: The Pelican Test
@@ -54,7 +75,7 @@ https://github.com/user-attachments/assets/448873b4-922a-4cac-b421-70a189394576
5475

5576
[View the SVG source file](doc/assets/pelican-bicycle-deepseek.svg)
5677

57-
## Quick Start
78+
## Install and Quick Start
5879

5980
### 1. Install the VS Code Extension
6081

@@ -126,6 +147,10 @@ During initialization, webcode reads project rule files from the root of the pri
126147

127148
If both `AGENTS.md` and `CLAUDE.md` exist, only `AGENTS.md` is sent. The browser extension no longer has a separate custom-instructions settings page.
128149

150+
## Configuration
151+
152+
VS Code settings use the `webcodeGateway.*` namespace. See the [site support guide](doc/PLATFORM_GUIDE_en.md) for site settings, the [MCP guide](doc/MCP_GUIDE_en.md) for server configuration, and the [browser mode guide](doc/BROWSER_MODE_GUIDE_en.md) for browser selection.
153+
129154
## Currently Supported AI Platforms and Additional Platform Support
130155

131156
webcode currently includes built-in support for the following AI platforms:
@@ -150,14 +175,37 @@ See the [build guide](doc/BUILD_GUIDE_en.md) for repository checkout, dependency
150175

151176
See the [FAQ guide](doc/FAQ_GUIDE_en.md) for first-launch setup, trigger-word issues, tool calls that executed but did not update the page, and tool-call history logs.
152177

178+
## Project Structure
179+
180+
- `gateway-vscode/`: VS Code extension, Gateway, MCP, and local tools.
181+
- `bridge-browser/`: browser extension and page-bridge logic.
182+
- `shared/`: types and logic shared across workspace packages.
183+
- `evals/`: unit evaluations, end-to-end scenarios, and QA scripts.
184+
- `doc/`: user, build, and development guides.
185+
186+
## Development and Tests
187+
188+
Requires Node.js 22 and pnpm 10.25.0. From the repository root:
189+
190+
```bash
191+
pnpm install
192+
pnpm --filter @webcode/shared run build
193+
pnpm build
194+
pnpm test
195+
pnpm test:extension
196+
pnpm lint
197+
```
198+
199+
See the [build guide](doc/BUILD_GUIDE_en.md) and [documentation index](doc/README_en.md) for command scope and browser end-to-end testing.
200+
153201
## Contributing
154202

155-
Issues and pull requests are welcome.
203+
Issues and pull requests are welcome. Read the [contributing guide](CONTRIBUTING.md) before opening a pull request. For security reports, see [SECURITY.md](SECURITY.md). The code of conduct is still a draft pending maintainer review: [CODE_OF_CONDUCT.md](CODE_OF_CONDUCT.md).
156204

157205
## Acknowledgments
158206

159207
Thanks to the [LINUX DO](https://linux.do/) community for providing a platform for technical discussions and open-source sharing.
160208

161209
## License
162210

163-
[MIT License](LICENSE)
211+
This repository is licensed under the MIT License. See [LICENSE](LICENSE).

‎SECURITY.md‎

Lines changed: 13 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,13 @@
1+
# 安全策略
2+
3+
## 报告安全问题
4+
5+
安全漏洞请勿通过公开 Issue 发布可直接利用的细节。
6+
7+
**待确认：** 仓库尚未提供私密安全报告渠道。维护者需确认并补充联系方式或 GitHub 私密漏洞报告入口后，本节方可作为完整的报告指引。
8+
9+
在报告渠道确认前，请避免在公开讨论中披露漏洞利用步骤、受影响用户数据或可复现的敏感信息。
10+
11+
## 支持范围
12+
13+
项目当前受支持版本和修复时限尚未定义，待维护者确认后补充。

0 commit comments

Comments
 (0)