Skip to content

Commit 81fb282

Browse files
newbe36524newbe36524
authored
new home (#10)
1 parent f02fc16 commit 81fb282

54 files changed

Lines changed: 7783 additions & 164 deletions

File tree

Some content is hidden

Large Commits have some content hidden by default. Use the searchbox below for content that may be hidden.

‎docs/quick-start/installation.md‎

Lines changed: 107 additions & 123 deletions
Original file line numberDiff line numberDiff line change
@@ -24,6 +24,10 @@ PCode 使用 PostgreSQL 作为其数据库。运行 PostgreSQL 的推荐方式
2424
<Tabs>
2525
<TabItem value="win" label="Windows">
2626
下载并安装 [Docker Desktop for Windows](https://www.docker.com/products/docker-desktop/)
27+
28+
:::tip 替代安装方式
29+
如果您更倾向于使用原生安装程序，可以参阅 **[在 Windows 上安装 PostgreSQL](/docs/related-software-installation/postgresql/install-on-windows)** 获取详细的 EXE 安装步骤。
30+
:::
2731
</TabItem>
2832
<TabItem value="mac" label="macOS">
2933
下载并安装 [Docker Desktop for Mac](https://www.docker.com/products/docker-desktop/)
@@ -66,142 +70,39 @@ docker run --name pcode-postgres \
6670

6771
PCode 需要 Node.js 18.0 或更高版本。
6872

69-
#### 验证 Node.js 安装
73+
**安装指南**：请参阅 [Node.js 安装指南](/docs/related-software-installation/nodejs/installation)
7074

71-
```bash
72-
node --version
73-
```
74-
75-
如果 Node.js 未安装或您的版本低于 18.0：
76-
77-
<Tabs>
78-
<TabItem value="win" label="Windows">
79-
从 [nodejs.org](https://nodejs.org/) 下载并安装 LTS 版本
80-
</TabItem>
81-
<TabItem value="mac" label="macOS">
82-
使用 Homebrew 安装：
83-
84-
```bash
85-
brew install node
86-
```
87-
</TabItem>
88-
<TabItem value="linux" label="Linux">
89-
使用您的包管理器安装：
90-
91-
```bash title="Ubuntu/Debian"
92-
sudo apt-get install nodejs npm
93-
```
94-
</TabItem>
95-
</Tabs>
96-
97-
#### 验证 npm 安装
75+
**验证安装**：
9876

9977
```bash
78+
node --version
10079
npm --version
10180
```
10281

10382
### OpenSpec CLI
10483

105-
OpenSpec 是一个用于管理提案和规范的工具。全局安装它：
84+
OpenSpec 是一个用于管理提案和规范的工具。
10685

107-
```bash
108-
npm install -g @fission-ai/openspec@latest
109-
```
86+
**安装指南**：请参阅 [OpenSpec 安装指南](/docs/related-software-installation/openspec/setup-openspec)
11087

111-
验证安装：
88+
**验证安装**：
11289

11390
```bash
11491
openspec --version
11592
```
11693

11794
### Claude Code CLI
11895

119-
PCode 的 AI 驱动功能需要 Claude Code CLI。全局安装它：
96+
PCode 的 AI 驱动功能需要 Claude Code CLI。
12097

121-
```bash
122-
npm install -g @anthropic-ai/claude-code
123-
```
98+
**安装指南**：请参阅 [Claude Code 安装指南](/docs/related-software-installation/claude-code/setup-claude-code-with-zai)
12499

125-
验证安装：
100+
**验证安装**：
126101

127102
```bash
128103
claude --version
129104
```
130105

131-
## 验证您的环境
132-
133-
在继续之前，使用此脚本验证所有先决条件是否已正确安装：
134-
135-
```bash title="check-environment.sh"
136-
#!/bin/bash
137-
138-
echo "检查 PCode 先决条件..."
139-
echo ""
140-
141-
# 检查 Node.js
142-
echo -n "Node.js: "
143-
if command -v node &> /dev/null; then
144-
NODE_VERSION=$(node --version)
145-
echo "✓ $NODE_VERSION"
146-
else
147-
echo "✗ 未安装"
148-
fi
149-
150-
# 检查 npm
151-
echo -n "npm: "
152-
if command -v npm &> /dev/null; then
153-
NPM_VERSION=$(npm --version)
154-
echo "✓ $NPM_VERSION"
155-
else
156-
echo "✗ 未安装"
157-
fi
158-
159-
# 检查 Docker
160-
echo -n "Docker: "
161-
if command -v docker &> /dev/null; then
162-
DOCKER_VERSION=$(docker --version)
163-
echo "✓ $DOCKER_VERSION"
164-
else
165-
echo "✗ 未安装"
166-
fi
167-
168-
# 检查 PostgreSQL
169-
echo -n "PostgreSQL: "
170-
if docker ps --filter "name=pcode-postgres" --format "{{.Names}}" | grep -q "pcode-postgres"; then
171-
echo "✓ 运行中 (pcode-postgres 容器)"
172-
else
173-
echo "✗ 未运行"
174-
fi
175-
176-
# 检查 OpenSpec CLI
177-
echo -n "OpenSpec CLI: "
178-
if command -v openspec &> /dev/null; then
179-
OPENSPEC_VERSION=$(openspec --version)
180-
echo "✓ $OPENSPEC_VERSION"
181-
else
182-
echo "✗ 未安装"
183-
fi
184-
185-
# 检查 Claude Code CLI
186-
echo -n "Claude Code CLI: "
187-
if command -v claude &> /dev/null; then
188-
CLAUDE_VERSION=$(claude --version)
189-
echo "✓ $CLAUDE_VERSION"
190-
else
191-
echo "✗ 未安装"
192-
fi
193-
194-
echo ""
195-
echo "环境检查完成！"
196-
```
197-
198-
将此脚本保存为 `check-environment.sh`，使其可执行并运行：
199-
200-
```bash
201-
chmod +x check-environment.sh
202-
./check-environment.sh
203-
```
204-
205106
## 部署软件包
206107

207108
PCode 以软件包的形式分发，您需要下载并解压到本地机器。
@@ -240,20 +141,103 @@ cd pcode
240141
</TabItem>
241142
</Tabs>
242143

144+
## 软件包结构
145+
146+
解压后的 PCode 软件包包含以下目录结构和文件：
147+
148+
<Tabs>
149+
<TabItem value="win" label="Windows">
150+
```text
151+
pcode/
152+
├── config/ # 用户配置覆盖目录
153+
│ ├── appsettings.yml # 用户配置文件（YAML 格式，最高优先级）
154+
│ └── README.md # 配置系统详细说明文档
155+
├── lib/ # 应用依赖和运行时文件目录
156+
│ ├── PCode.Web.dll # 主程序
157+
│ ├── appsettings.yml # 基础配置
158+
│ ├── appsettings.Production.yml # 生产环境配置
159+
│ └── [其他依赖库...]
160+
├── start.bat # Windows 启动脚本
161+
├── README.md # 软件包说明文档（中文）
162+
└── README_en.md # 软件包说明文档（英文）
163+
```
164+
</TabItem>
165+
<TabItem value="mac" label="macOS">
166+
```text
167+
pcode/
168+
├── config/ # 用户配置覆盖目录
169+
│ ├── appsettings.yml # 用户配置文件（YAML 格式，最高优先级）
170+
│ └── README.md # 配置系统详细说明文档
171+
├── lib/ # 应用依赖和运行时文件目录
172+
│ ├── PCode.Web.dll # 主程序
173+
│ ├── appsettings.yml # 基础配置
174+
│ ├── appsettings.Production.yml # 生产环境配置
175+
│ └── [其他依赖库...]
176+
├── start.sh # macOS/Linux 启动脚本
177+
├── README.md # 软件包说明文档（中文）
178+
└── README_en.md # 软件包说明文档（英文）
179+
```
180+
</TabItem>
181+
<TabItem value="linux" label="Linux">
182+
```text
183+
pcode/
184+
├── config/ # 用户配置覆盖目录
185+
│ ├── appsettings.yml # 用户配置文件（YAML 格式，最高优先级）
186+
│ └── README.md # 配置系统详细说明文档
187+
├── lib/ # 应用依赖和运行时文件目录
188+
│ ├── PCode.Web.dll # 主程序
189+
│ ├── appsettings.yml # 基础配置
190+
│ ├── appsettings.Production.yml # 生产环境配置
191+
│ └── [其他依赖库...]
192+
├── start.sh # macOS/Linux 启动脚本
193+
├── README.md # 软件包说明文档（中文）
194+
└── README_en.md # 软件包说明文档（英文）
195+
```
196+
</TabItem>
197+
</Tabs>
198+
199+
### 目录说明
200+
201+
| 目录/文件 | 说明 |
202+
|-----------|------|
203+
| **config/** | 用户配置覆盖目录。此目录中的配置文件具有最高优先级，会覆盖其他位置的配置。 |
204+
| **config/appsettings.yml** | 用户配置文件（YAML 格式）。这是您应该修改的主要配置文件，具有最高优先级。 |
205+
| **config/README.md** | 配置系统的详细说明文档，包含所有配置选项的完整参考。 |
206+
| **lib/** | 应用程序依赖和运行时文件目录，包含主程序和所有依赖库。 |
207+
| **lib/PCode.Web.dll** | PCode 的主程序（.NET 程序集）。 |
208+
| **lib/appsettings.yml** | 基础配置文件，包含默认配置值。 |
209+
| **lib/appsettings.Production.yml** | 生产环境配置文件，包含生产环境的默认值。 |
210+
| **start.sh** / **start.bat** | 启动脚本（Linux/macOS 使用 `.sh`，Windows 使用 `.bat`）。 |
211+
| **README.md** / **README_en.md** | 软件包说明文档，包含基本的使用信息和注意事项。 |
212+
213+
### 配置加载优先级
214+
215+
PCode 使用三层配置加载机制，优先级从低到高为：
216+
217+
1. **lib/appsettings.yml** - 基础配置（默认值）
218+
2. **lib/appsettings.Production.yml** - 生产环境配置（环境特定值）
219+
3. **config/appsettings.yml** - 用户配置覆盖（最高优先级）
220+
221+
当同一配置项在多个文件中定义时，优先级更高的配置会覆盖优先级较低的配置。这种设计允许您：
222+
- 保留默认配置不变
223+
- 在 `config/` 目录中仅覆盖需要修改的配置项
224+
- 升级软件包时无需重新配置（只需保留 `config/` 目录）
225+
226+
:::tip 推荐做法
227+
修改配置时，请在 `config/appsettings.yml` 中进行修改，而不是直接编辑 `lib/` 目录中的文件。这样在软件包升级时，您的配置更改将被保留。
228+
:::
229+
243230
## 配置数据库连接
244231

245-
PCode 需要连接到您的 PostgreSQL 数据库。数据库连接在 `appsettings.Production.json` 文件中配置。
232+
PCode 需要连接到您的 PostgreSQL 数据库。数据库连接在 `config/appsettings.yml` 文件中配置。
246233

247234
1. 导航到 PCode 目录
248-
2. 在文本编辑器中打开 `appsettings.Production.json`
235+
2. 在文本编辑器中打开 `config/appsettings.yml`
249236
3. 找到连接字符串部分：
250237

251-
```json
252-
{
253-
"ConnectionStrings": {
254-
"Default": "Host=127.0.0.1;Port=5432;Database=pcode;Username=postgres;Password=postgres"
255-
}
256-
}
238+
```yaml
239+
ConnectionStrings:
240+
Default: "Host=127.0.0.1;Port=5432;Database=pcode;Username=postgres;Password=postgres"
257241
```
258242
259243
4. 如果您使用不同的凭据，请更新连接字符串：
@@ -334,7 +318,7 @@ chmod +x start.sh
334318
tail -f logs/pcode.log
335319
```
336320

337-
4. **验证连接字符串**在 `appsettings.Production.json` 中
321+
4. **验证连接字符串**在 `config/appsettings.yml` 中
338322

339323
5. **检查端口可用性**：确保端口 `34567` 未被其他应用程序使用
340324

@@ -359,7 +343,7 @@ PCode 界面应该会加载，显示主仪表板。
359343
- **主机**: `127.0.0.1`（本地主机）
360344
361345
:::note
362-
端口 `34567` 是 PCode 使用的默认端口。如果您需要更改它，可以在 `appsettings.Production.json` 中修改配置。
346+
端口 `34567` 是 PCode 使用的默认端口。如果您需要更改它，可以在 `config/appsettings.yml` 中修改配置。
363347
:::
364348
365349
### 停止服务
@@ -403,7 +387,7 @@ docker stop pcode-postgres
403387
如果您看到连接错误：
404388

405389
1. 验证 PostgreSQL 是否正在运行：`docker ps | grep pcode-postgres`
406-
2. 检查 `appsettings.Production.json` 中的连接字符串
390+
2. 检查 `config/appsettings.yml` 中的连接字符串
407391
3. 确保端口 `5432` 未被防火墙阻止
408392

409393
### 端口已被占用

‎docs/related-software-installation/claude-code/_category_.json‎

Lines changed: 4 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,4 @@
1+
{
2+
"label": "Claude Code",
3+
"position": 2
4+
}

‎docs/related-software-installation/claude-code/setup-claude-code-with-zai.md‎

Lines changed: 83 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,83 @@
1+
---
2+
title: 安装 Claude Code
3+
description: 本指南将帮助您安装 Claude Code 并配置智谱 AI (ZAI) 模型。
4+
sidebar_position: 10
5+
---
6+
7+
# 安装 Claude Code
8+
9+
Claude Code 是一个强大的 AI 辅助编程工具，能够显著提升开发效率和代码质量。本指南将指导您安装 Claude Code 并配置智谱 AI (ZAI) 模型。
10+
11+
## 安装 Claude Code
12+
13+
### 为什么不推荐官方安装方式
14+
15+
Claude Code 官方提供了两种安装方式：
16+
- **Native 安装**：需要从 GitHub Releases 下载二进制文件
17+
- **官方脚本安装**：需要执行官方提供的安装脚本
18+
19+
由于网络原因，上述方式在国内网络环境下可能无法正常使用。因此，我们推荐使用 **NPM 安装方式**，这种方式更稳定且在国内网络环境下表现更好。
20+
21+
### 使用 NPM 安装
22+
23+
通过 NPM 可以非常方便地安装 Claude Code。请确保您已经安装了 Node.js 环境。
24+
25+
```bash
26+
npm install -g @anthropic-ai/claude-code
27+
```
28+
29+
安装完毕之后，可以通过以下命令验证安装是否成功：
30+
31+
```bash
32+
claude --version
33+
```
34+
35+
## 购买 ZAI 订阅
36+
37+
使用 ZAI 您需要先购买订阅并获得 API Key。对于代码编写来说，建议购买 Coding Plan 作为日常使用，这样会更加节约成本。
38+
39+
可以通过以下链接购买获得 **10% 优惠**：[https://www.bigmodel.cn/claude-code?ic=14BY54APZA](https://www.bigmodel.cn/claude-code?ic=14BY54APZA)
40+
41+
:::tip
42+
初次体验可以购买 lite 版本，价格更低。
43+
:::
44+
45+
购买成功之后可以通过以下地址创建 API Key：[https://bigmodel.cn/usercenter/proj-mgmt/apikeys](https://bigmodel.cn/usercenter/proj-mgmt/apikeys)
46+
47+
## 在 Claude Code 中配置 ZAI
48+
49+
官方提供了文档来说明如何在 Claude Code 中配置 ZAI 模型：[https://docs.bigmodel.cn/cn/coding-plan/tool/claude](https://docs.bigmodel.cn/cn/coding-plan/tool/claude)
50+
51+
ZAI 现在提供了一个简单的命令行工具 `coding-helper` 来帮助您配置 Claude Code。
52+
53+
```bash
54+
# 进入命令行界面，执行如下运行 Coding Tool Helper
55+
npx @z_ai/coding-helper
56+
```
57+
58+
运行之后会进入一个交互式的命令行界面，按照提示输入您的 API Key 并选择 Claude Code 即可完成配置。
59+
60+
## 初次体验
61+
62+
完成配置之后，您就可以在 Claude Code 中使用 ZAI 模型了。在命令行中输入：
63+
64+
```bash
65+
claude
66+
```
67+
68+
即可进入 Claude Code 的交互界面。在交互界面中，可以进行围绕当前文件夹的上下文进行代码生成和修改。
69+
70+
:::note
71+
如果第一次呼出的时候要求填写一个 API Key，您可以随便输入一个字符串，因为这不是我们需要的 Key，真正的 Key 已经通过 `coding-helper` 工具配置好了。
72+
:::
73+
74+
## IDE 插件
75+
76+
Claude Code 也提供了 VSCode 和 JetBrains 系列 IDE 的插件，可以让您在熟悉的开发环境中使用 Claude Code 和 ZAI 模型。
77+
78+
- **VSCode 插件市场链接**：[https://marketplace.visualstudio.com/items?itemName=anthropic.claude-code](https://marketplace.visualstudio.com/items?itemName=anthropic.claude-code)
79+
- **JetBrains 插件市场链接**：[https://plugins.jetbrains.com/plugin/27310-claude-code-beta-](https://plugins.jetbrains.com/plugin/27310-claude-code-beta-)
80+
81+
:::tip
82+
使用 IDE 插件比起命令行工具来说，体验会更好一些，因为它可以识别到您鼠标选中的代码片段，以及您当前打开的文件，从而提供更精准的代码生成和修改建议。
83+
:::

‎docs/related-software-installation/nodejs/_category_.json‎

Lines changed: 4 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,4 @@
1+
{
2+
"label": "Node.js",
3+
"position": 2
4+
}

0 commit comments

Comments
 (0)