Skip to content

feat: add AGENTS.md #358

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
YufJi merged 3 commits into from
May 8, 2026
Merged

feat: add AGENTS.md #358

Changes from all commits
Commits
Show all changes
3 commits
Select commit Hold shift + click to select a range
87239e1
Add spec-kit
YufJi Mar 31, 2026
bebc495
Merge remote-tracking branch 'origin/test' into feature/spec-kit
YufJi Apr 29, 2026
53f23f4
Remove outdated templates and add new LCAP Agent Guide documentation
YufJi Apr 29, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
138 changes: 138 additions & 0 deletions AGENTS.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,138 @@
# LCAP Template - Agent Guide

> 低代码应用模板技术架构说明

## 项目结构

```
lcap-template/
├── packages/
│ ├── basic/ # 通用纯函数库，不依赖框架
│ ├── vue2/ # Vue 2 框架应用模板
│ ├── vue3/ # Vue 3 框架应用模板
│ └── react/ # React 框架应用模板
├── mini-folder/
│ ├── taro/ # Taro 小程序应用模板
│ └── build/ # 小程序构建配置
├── scripts/ # 根目录脚本
└── docs/ # 文档输出目录
```

## 技术栈

### 核心依赖
- **Node.js**: >= 18
- **pnpm**: >= 8 (packageManager: pnpm@9.10.0)
- **Turbo**: 构建编排
Comment on lines +24 to +26
Copy link
Copy Markdown
Contributor

@coderabbitai coderabbitai Bot Apr 29, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

⚠️ Potential issue | 🟡 Minor

🧩 Analysis chain

🏁 Script executed:

git ls-files | grep -i "agent"

Repository: netease-lcap/lcap-template

Length of output: 80

🏁 Script executed:

cat AGENTS.md

Repository: netease-lcap/lcap-template

Length of output: 2756

🏁 Script executed:

fd "package" --type f | head -20

Repository: netease-lcap/lcap-template

Length of output: 402

🏁 Script executed:

cat package.json | head -30

Repository: netease-lcap/lcap-template

Length of output: 912

🏁 Script executed:

rg "packageManager|pnpm" package.json

Repository: netease-lcap/lcap-template

Length of output: 234

🏁 Script executed:

rg "pnpm" --type json packages/ | grep -i version

Repository: netease-lcap/lcap-template

Length of output: 52

统一 pnpm 最低版本要求至 9.10.0+

package.json 中 packageManager 字段指定的版本为 pnpm@9.10.0，但 AGENTS.md 第 25 行写的是 >= 8，两者不一致。建议更新文档以避免混淆开发者。

建议改法 
-- **pnpm**: >= 8 (packageManager: pnpm@9.10.0)
+- **pnpm**: >= 9.10.0 (packageManager: pnpm@9.10.0)
🤖 Prompt for AI Agents 
Verify each finding against the current code and only fix it if needed.

In `@AGENTS.md` around lines 24 - 26, Update the pnpm minimum version in AGENTS.md
to match package.json's packageManager value by changing the pnpm requirement
from ">= 8" to ">= 9.10.0" (or explicitly mention "pnpm@9.10.0+") so the
document aligns with the packageManager field; ensure the textual entry
referencing pnpm in AGENTS.md and any adjacent version notes reflect the same
"pnpm@9.10.0" baseline.


### 各包技术栈

| 包名 | 框架 | 构建工具 | 状态管理 | 主要依赖 |
|------|------|----------|----------|----------|
| `@lcap/basic-template` | 无 | Rollup | 无 | axios, lodash, moment |
| `@lcap/vue-template` | Vue 2.6.14 | Webpack 5 | Pinia 2.2.8 | @vue/composition-api |
| `@lcap/vue3-template` | Vue 3.5.13 | Rspack 1.3.10 | Pinia 2.3.1 | vue-router 4 |
| `@lcap/react-template` | React | 自定义脚本 | - | - |
| `taro-mini-vue2` | Vue 2.6.14 | Taro 3.6.35 | - | 小程序多端构建 |

## 常用命令

```bash
# 安装依赖
pnpm install

# 构建所有包
pnpm build

# 运行测试
pnpm test

# 修改版本号
pnpm change:version --version 1.0.0

# 部署静态资源
pnpm run deploy --platform a --username b --password c
```
Comment on lines +54 to +55
Copy link
Copy Markdown
Contributor

@coderabbitai coderabbitai Bot Apr 29, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

⚠️ Potential issue | 🟠 Major

避免在文档示例中直接出现账号/密码参数（安全最佳实践）

第 54 行的部署示例将 --username / --password 以明文参数形式写在命令行里。即使是占位符，实际使用时也很容易被复制粘贴成真实凭据，造成泄漏风险。建议改为：使用环境变量（或 CI secret）并在文档中示例 --username "$DEPLOY_USER" / --password "$DEPLOY_PASS"，或提供不带明文密码的认证方式。

✅ 建议改法示例 
-pnpm run deploy --platform a --username b --password c
+pnpm run deploy --platform a --username "$DEPLOY_USER" --password "$DEPLOY_PASS"
📝 Committable suggestion

‼️ IMPORTANT
Carefully review the code before committing. Ensure that it accurately replaces the highlighted code, contains no missing lines, and has no issues with indentation. Thoroughly test & benchmark the code to ensure it meets the requirements.

Suggested change
pnpm run deploy --platform a --username b --password c
```
pnpm run deploy --platform a --username "$DEPLOY_USER" --password "$DEPLOY_PASS"
🤖 Prompt for AI Agents 
Verify each finding against the current code and only fix it if needed.

In `@AGENTS.md` around lines 54 - 55, Replace the literal --username and
--password placeholders in the pnpm run deploy example with references to
environment variables or CI secrets to avoid showing credentials in docs;
specifically update the example invocation that contains the flags --username
and --password to instead use environment-backed values (e.g., use
"$DEPLOY_USER" and "$DEPLOY_PASS" or instruct readers to export
DEPLOY_USER/DEPLOY_PASS or use CI secret injection) or provide an alternative
auth method, and update the surrounding text to instruct using environment
variables/CI secrets rather than inline plaintext credentials.


### 包级命令

```bash
# basic 包
cd packages/basic
pnpm build # Rollup 构建 + 类型生成
pnpm test # Jest 测试
pnpm doc # TypeDoc 生成文档

# vue2 包
cd packages/vue2
pnpm build # Webpack 构建
pnpm dev # 开发服务器

# vue3 包
cd packages/vue3
pnpm build # Rspack 构建
```

## 架构设计

### Monorepo 架构
- 使用 pnpm workspaces 管理
- Turbo 编排构建任务（支持依赖拓扑）
- 包间通过 `workspace:*` 引用

### 核心设计原则
1. **basic 包**: 纯函数库，框架无关，被其他包依赖
2. **框架包** (vue2/vue3/react): 依赖 basic 包，提供框架特定的模板实现
3. **小程序包**: 独立的 Taro 应用，支持多端输出

### 构建流程
```
LCAP_RELEASE=1 pnpm build
→ turbo run build (按依赖顺序)
→ basic: Rollup 打包 → dist/ + typings/
→ vue2: Webpack 构建 → dist/
→ vue3: Rspack 构建 → dist/
→ react: 自定义构建 → dist/
```

## CI/CD

### 工作流
- **test.yml**: PR 到 test/test-v* 分支时运行测试
- **build.yml**: push 到 release/* 分支时构建并上传产物
- **deploy.yml**: 部署测试环境
- **doc.yml**: 部署文档站点

### 发布流程
1. 修改版本: `pnpm change:version --version x.x.x`
2. 提交到 release/* 分支触发构建
3. 构建产物自动上传并触发后续发布流程

## 开发规范

### Git 提交
使用 Conventional Commits:
- `feat:` 新功能
- `fix:` 修复 bug
- `docs:` 文档更新
- `refactor:` 代码重构
- `test:` 测试相关

### 代码风格
- Prettier 格式化
- lint-staged 在提交前自动格式化
- 类型定义统一放在 `typings/` 或 `types/` 目录

## 注意事项

1. **Node 版本**: 必须使用 Node.js 18+
2. **包管理器**: 强制使用 pnpm，不要混用 npm/yarn
3. **构建顺序**: basic 包必须先构建，其他包依赖它
4. **环境变量**: `LCAP_RELEASE=1` 用于生产构建
5. **小程序**: taro 包使用独立构建流程，与主包不共享配置

## 参考文档

- [API 文档](https://netease-lcap.github.io/lcap-template/)
- [basic 包详细文档](packages/basic/README.md)
- [vue3 包详细文档](packages/vue3/source/README.md)
Loading