Руководство по началу работы с ZCode

ZCode — это среда разработки агентов-разработчиков, выпущенная Zhipu, также известная как Agentic Development Environment, сокращённо ADE. В отличие от традиционных редакторов, она поставляется с ИИ-ассистентом, который может глубоко работать с проектами, просматривать проекты, изменять файлы, выполнять команды и разбирать изменения кода.

ZCode может подключать ИИ-агентов к реальным проектам, выполняя весь процесс разработки — анализ требований, изменение кода, тестирование, ревью кода и проверки перед запуском — в одном месте.

Обычные ИИ-инструменты могут генерировать лишь разрозненные фрагменты кода. ZCode поддерживает постановку полных задач разработки на естественном языке, что подходит пользователям, которые хотят управлять разработкой с помощью естественного языка.

Суть ZCode не в простом чате, а в непрерывном продвижении полной задачи вокруг цели разработки.

Концепция Описание Подходящие сценарии
ZCode Среда разработки для ИИ-агентов. Для тех, кто хочет с помощью естественного языка продвигать разработку реальных проектов.
Агент ZCode Агент, отвечающий за понимание задач, чтение контекста, изменение кода и проверку результатов. Декомпозиция сложных требований, генерация кода, отладка, тестирование.
Долгосрочная задача Задачи разработки, которые занимают много времени и включают много шагов. Рефакторинг модулей, исправление сложных ошибок, реализация полных функций.
Рабочее пространство Место, где ZCode работает с файлами проекта, терминалом, статусом Git и контекстом задачи. Откройте существующий проект или создайте новый проект в каталоге.

Для чего хорошо подходит ZCode

ZCode подходит для разработки, требующей непрерывного контекста. Он может читать файлы, понимать структуру проекта, выполнять команды и предоставлять сводку после завершения изменений.

Такая возможность подходит для реальной инженерной работы, а не только для разовых вопросов и ответов.

Тип задачи Что можно попросить ZCode сделать Пример запроса
Разработка новой функции Проверьте структуру проекта на основе требований, создайте или измените связанные файлы. Помогите мне добавить страницу входа в этот проект и интегрировать её с существующей маршрутизацией.
Исправление ошибок Найдите причину ошибки, измените код и выполните команды проверки. Исправьте проблему, из-за которой страница мерцает после нажатия кнопки на мобильном устройстве.
Понимание кода Разберитесь в связях между модулями и объясните цепочку вызовов функции от точки входа до реализации. Помогите мне объяснить, как работает платёжный поток в этом проекте.
Ревью кода Проверьте риски изменений, дайте встроенные предложения или направления улучшения. Пожалуйста, проверьте текущие изменения, уделив особое внимание рискам регрессии.
Подготовка к релизу Сгенерируйте журнал изменений, оформите примечания к релизу, проверьте статус Git. Сгенерируйте черновик примечаний к релизу на основе последних коммитов.

Установка ZCode

После перехода на официальный китайский сайт ZCode вы можете нажать на пункт загрузки на главной странице.

Адрес официального сайта:https://zcode.z.ai/cn。

На странице официального сайта показаны доступные в настоящее время версии для скачивания с поддержкой Windows, macOS и Linux. Обычно официальный сайт показывает кнопку скачивания для текущей системы:

После скачивания просто нажмите, чтобы установить:

Базовая подготовка после установки

При первом запуске вы попадёте на страницу «Первоначальная настройка». После её завершения нажмите «Подключиться и использовать» в левом нижнем углу, чтобы перейти на страницу входа:

Если вы хотите использовать сервисы моделей, вам также необходимо выполнить настройку, связанную с API Key илиCoding Plan. Вы также можете войти, а затем настроить её на странице настроек:

Официальная бесплатная квота в настоящее время очень ограничена и её в основном не хватает. Мы рекомендуем следующие пакеты Coding Plan:

Далее давайте возьмёмCoding Plan от ByteDance Arkв качестве примера для настройки. Посетите ArkАкция Coding Plan, оформите подписку на план при необходимости. Если использование низкое, достаточно версии Lite; если использование очень высокое, можно использовать версию Pro.

После успешной покупки нажмитеСоздать свой API Key：

Затем нажмите кнопку «Create»:

Нажмите на маленький значок глаза ниже, чтобы увидеть API key. При необходимости просто скопируйте его:

У разных инструментов разные конфигурации Base URL в зависимости от совместимого протокола:

  • Инструменты, совместимые с протоколом Anthropic API:https://ark.cn-beijing.volces.com/api/coding
  • Инструменты, совместимые с протоколом OpenAI API:https://ark.cn-beijing.volces.com/api/coding/v3

Здесь мы выбираемhttps://ark.cn-beijing.volces.com/api/coding, укажите свой API-ключ. Список моделей позволяет добавлять несколько моделей. Здесь впишитеKimi-K2.6, также можно добавить другие модели, напримерDeepSeek-V4-Pro：

После добавления можно проверить, доступна ли модель:

Добавленную модель можно увидеть в правом нижнем углу диалогового окна на главной странице:

ZCode предоставляет страницы для настройки API-ключа, статистики использования, обратной связи пользователей и поддержки.

Первое использование ZCode

Можно начать с простого проекта, попросив ZCode создать мини-игру для браузера или объяснить структуру каталогов существующего проекта.

Это поможет быстро понять, как работает ZCode.

Открытие или создание рабочей области

Рабочую область можно понимать как каталог проекта, который ZCode обрабатывает в данный момент.

Можно открыть существующий каталог проекта или начать новый проект в пустом каталоге.

ZCode будет читать файлы, выполнять команды и управлять изменениями в этом каталоге.

Создание новой задачи

В ZCode задача — это базовая единица, которая управляет работой агента.

Официальные примеры показывают, как описывать задачи на естественном языке.

На странице отображается сочетание клавиш для создания новой задачи.⌘N。

Пример создания новой задачи:

Create a smart Gomoku web game, including a game board, player moves, win/loss detection, and a simple computer opponent.

Наблюдение за процессом выполнения

Как только задача запускается, проект анализируется с учётом цели и выполняется шаг за шагом.

Вы можете видеть прогресс задачи, журналы выполнения, изменения файлов, вывод терминала и состояние Git.

Это надёжнее, чем просто копировать фрагмент кода, сгенерированный ИИ, потому что это позволяет вернуть код в реальный проект для проверки.

Область интерфейса Назначение На что следует обратить внимание новичкам
Прогресс задачи Показывает разбивку и статус выполнения текущей задачи. Убедитесь, что агент продвигается к цели.
Вывод терминала Показывает результаты выполнения команд. Следите за ошибками и за тем, проходят ли команды проверки.
Изменения файлов Показывает файлы, которые были добавлены, изменены или удалены. Проверьте, соответствуют ли изменения ожиданиям.
Статус Git Показывает состояние системы контроля версий для текущего рабочего пространства. Перед коммитом убедитесь, что в него включены только нужные вам изменения.

Полный пример для начинающих

Ниже мы используем простой фронтенд-проект, чтобы продемонстрировать, как назначать задачи ZCode.

Этот пример не зависит от бэкенда, поэтому он подходит для начинающих, чтобы разобраться в процессе.

Пример

Пожалуйста, помоги мне создать простой проект веб-страницы со счётчиком.

Требования:
1. Используй три файла: HTML, CSS и JavaScript.
2. Отображай текущее значение счётчика на странице.
3. Предоставь три кнопки: «Добавить единицу», «Вычесть единицу» и «Сбросить».
4. Сделай стиль простым и подходящим для чтения начинающими.
5. После завершения, пожалуйста, выполни необходимые проверки и скажи мне, какие файлы были созданы.

Этот запрос ясно сообщает ZCode, что создать, какие файлы использовать, какие функции включить и что о результатах нужно сообщить после завершения.

Чем конкретнее запрос, тем выше вероятность, что выполнение Агента будет соответствовать ожиданиям.

Затем появится запрос разрешения; предоставь разрешение и нажми подтверждение:

Возможная структура сгенерированного проекта

Если вы запустите эту задачу в пустом каталоге, ZCode может создать структуру файлов, похожую на приведённую ниже.

counter-demo/
├── index.html
├── styles.css
└── app.js

Вы можете просмотреть исходный код:

Эффект отображения исходного кода:

Как писать хорошие промпты для ZCode

ZCode понимает естественный язык, но это не значит, что короткие промпты всегда лучше.

Хороший промпт должен включать цель, охват, ограничения и критерии приёмки.

Это позволяет агенту более надёжно планировать и выполнять задачи.

Компонент Описание Пример
Цель Опишите, чего вы хотите достичь в конечном итоге. Добавьте страницу пользовательских настроек.
Область действия Укажите, какие части следует изменить, а какие — нет. Изменяйте только frontend-страницу, не изменяйте backend API.
Ограничения Укажите технологический стек, стиль и требования к совместимости. Используйте существующую библиотеку компонентов, не добавляйте новые зависимости.
Критерии приёмки Объясните, как определить успех после завершения. Запуск npm test проходит успешно, и вёрстка корректно работает на мобильных устройствах.

Пример

Пожалуйста, помогите исправить проблему, из-за которой кнопка на странице входа перекрывается на мобильных устройствах.

Область видимости:
- Изменяйте только файлы, связанные со страницей входа.
- Не изменяйте API бэкенда.
- Не добавляйте сторонние зависимости.

Требования:
- Сохраняйте существующий визуальный стиль.
- Адаптируйте под мобильные экраны шириной 375px.
- После изменения объясните, какие файлы были изменены.
- Если в проекте есть команды тестирования или проверки, запустите их и сообщите о результатах.

Не пишите просто «помогите мне это оптимизировать». У такого запроса слишком широкая область действия, и агенту будет сложно определить, что вы действительно хотите.

Типовые рабочие процессы

Преимущество ZCode заключается в объединении процесса разработки.

Вы можете провести задачу от описания требований до изменения кода, а затем до проверки и подведения итогов.

Создание функции с нуля

Когда вы хотите создать новую функцию, сначала уточните границы этой функции.

Если в проекте уже есть технологический стек, также потребуйте от ZCode следовать существующим соглашениям.

Пример

Пожалуйста, добавьте страницу "О нас" в текущий проект.

Требования:
- Используйте существующий в проекте подход к маршрутизации.
- Переиспользуйте существующие компоненты макета страницы.
- Страница включает три раздела: заголовок, введение и контактную информацию.
- Не добавляйте новых зависимостей.
- После завершения, пожалуйста, перечислите добавленные и изменённые файлы.

Понимание существующего кода

Когда вы принимаете незнакомый проект, вы можете сначала попросить ZCode объяснить структуру, а не сразу изменять код.

Это помогает снизить риск внесения непреднамеренных изменений.

Пример

Пожалуйста, пока не изменяйте никакие файлы.

Помогите мне прочитать текущую структуру проекта и объясните:
- Где находится точка входа приложения.
- Где определяются маршруты.
- Где инкапсулируются запросы API.
- Каковы команды сборки и тестирования соответственно.

Проверки перед коммитом

Перед коммитом кода вы можете попросить ZCode проверить текущие изменения.

Это поможет выявить отсутствующие файлы, потенциальные регрессии и отсутствующие тесты.

Пример

Пожалуйста, проверьте изменения в текущем рабочем пространстве.

Обратите внимание на проверку:
- Есть ли очевидные ошибки.
- Не нарушена ли существующая функциональность.
- Есть ли неиспользуемые переменные или отладочный код.
- Нужны ли дополнительные тесты.

Сначала предоставьте список проблем; не изменяйте файлы напрямую.

Подтверждение безопасности и разрешения

ZCode переходит в режим подтверждения перед критическими командами, изменениями файлов и операциями с высокими привилегиями. Это предотвращает выполнение Агентом опасных операций без вашего ведома.

Вы можете прочитать детали подтверждения перед выполнением команды, а затем решить, разрешить ли её.

Тип операции Почему требуется подтверждение Рекомендуемая практика
Изменение файлов Изменит код проекта. Убедитесь, что путь к файлу и цель изменения указаны верно.
Удалять файлы Может привести к потере данных. Перед удалением проверьте содержимое файла и при необходимости создайте резервную копию.
Запуск команд Команды могут устанавливать зависимости, запускать службы или изменять окружение. Убедитесь в назначении команды и избегайте выполнения неизвестных высокорисковых команд.
Операции Git Может повлиять на историю коммитов или удалённый репозиторий. Перед коммитом и отправкой проверьте git status.

Если вы не уверены, безопасна ли команда, сначала попросите ZCode объяснить её назначение, а не разрешайте её сразу выполнять.

Общие команды и методы проверки

ZCode может использовать терминал для запуска команд проекта.

Конкретные команды зависят от технологического стека вашего проекта.

Ниже приведены некоторые команды, которые встречаются в официальных примерах и типичных сценариях разработки.

Команда Функция Пример
pwd Просмотреть текущий каталог. Проверить, находится ли текущий терминал ZCode в каталоге проекта.
git status --short Просмотреть изменения Git в кратком формате. Проверить, какие файлы были изменены перед коммитом.
node --check app.js Проверить синтаксис файла JavaScript. Проверить, есть ли в app.js синтаксические ошибки.
npm test Запустить тесты проекта. Подходит для проектов на JavaScript или frontend-проектов.
npm run build Запустите сборку проекта. Убедитесь, что проект можно правильно упаковать перед релизом. 
$ git status --short
 M src/App.js
 M src/styles.css

Приведённый выше вывод показывает, что были изменены два файла.

Перед коммитом следует убедиться, что все эти изменения соответствуют ожиданиям.

Обзор продвинутых возможностей

Помимо выполнения задач на рабочем столе, документация ZCode также упоминает некоторые продвинутые возможности.

Вам не нужно осваивать их все сразу на начальном этапе, но для начала можно понять, какие проблемы они решают.

Способность Описание Когда использовать
Удалённое управление Отслеживайте задачи Agent или управляйте ими удалённо. Когда задача занимает много времени и вы хотите продолжать проверять прогресс, покинув компьютер.
Канал бота Запуск и продвижение задач через Feishu или WeChat Bot. Командная работа, отслеживание прогресса с мобильных устройств и удалённые дополнительные инструкции.
Навык Предоставление специализированных возможностей или рабочих процессов для конкретных задач. Когда вы многократно выполняете однотипные задачи, например аудиты безопасности, генерацию документации или запуски тестов.
MCP-серверы Подключение внешних инструментов или источников данных к Агенту. Когда нужно подключить базу данных, базу знаний, внутреннюю систему или специализированные инструменты.
Субагенты Позвольте разным агентам решать разные подзадачи. Когда большая задача требует параллельного исследования, проверки или разделения труда.

Частые вопросы новичков

Ниже приведены некоторые распространённые проблемы, с которыми вы можете столкнуться при первом использовании ZCode.

Будет ли ZCode автоматически изменять мой проект без разрешения?

Критические операции ZCode проходят через процедуру подтверждения.

Перед разрешением проверьте файлы, которые он будет изменять, и команды, которые он будет запускать.

Если вы хотите, чтобы он только читал проект, вы можете явно написать в запросе "не изменять файлы".

Стоит ли позволять ZCode делать много вещей одновременно?

Начинающим не рекомендуется сразу давать слишком большие задачи.

Лучше разбить задачу на более мелкие части.

Например, сначала попросите его разобраться в структуре проекта, затем изменить модуль и, наконец, запустить проверку.

Что делать, если задача не удалась

Сначала проверьте вывод терминала и сообщения об ошибках.

Затем попросите ZCode продолжить исправление, основываясь на ошибках.

Не спешите начинать совершенно другую задачу, иначе можете потерять контекст.

Когда требуется ручная проверка?

Когда речь идет о бизнес-логике, разрешениях, безопасности, платежах, удалении данных или операциях релиза, следует выполнять ручную проверку.

ИИ может помочь выявить проблемы, но окончательная ответственность по-прежнему лежит на разработчике.

Советы по обучению

Лучший способ изучить ZCode — не запоминать команды, а практиковаться, начиная с небольших задач.

Сначала вы можете использовать его для создания простой страницы, а затем попросить его объяснить сгенерированный код.

Затем попробуйте попросить его исправить небольшую ошибку и понаблюдайте, как он читает файлы, изменяет код и проверяет результаты.

Как только вы освоитесь с таким подходом к разработке, ориентированным на задачи, постепенно используйте такие возможности, как обзор кода, подготовка к релизу, Remote Control и Skill.

Рассматривайте ZCode как партнера по разработке, способного работать с проектами, а не как чат-бота, который только отвечает на вопросы. Так проще использовать его преимущества.

Другие расширения